{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "carrier": {
      "type": "string",
      "enum": ["dhl", "dhl_express", "dpag", "ups", "dpd", "hermes", "gls", "iloxx", "tnt", "fedex", "go", "parcel_one", "cargo_international"],
      "description": "acronym of the carrier you want to use"
    },
    "to": {
      "$ref": "#/definitions/address",
      "description": "the receivers address"
    },
    "from": {
      "$ref": "#/definitions/address",
      "description": "If missing, the default sender address (if defined in your shipcloud account) will be used"
    },
    "package": {
      "$ref": "#/definitions/package"
    },
    "service": {
      "type": "string",
      "enum": ["standard", "one_day" , "one_day_early", "cargo_international_express", "ups_express_1200", "dhl_europaket", "returns"],
      "default": "standard",
      "description": "The service that should be used for the shipment."
    },
    "reference_number": {
      "type": "string",
      "description": "a reference number (max. 30 characters) that you want this shipment to be identified with. You can use this afterwards to easier find the shipment in the shipcloud.io backoffice"
    },
    "description": {
      "type": "string",
      "description": "text that describes the contents of the shipment. This parameter is mandatory if you're using UPS and the following conditions are true: from and to countries are not the same; from and/or to countries are not in the EU; from and to countries are in the EU and the shipments service is not 'standard'. The parameter is also mandatory when using DHL Express as carrier."
    },
    "label": {
      "$ref": "#/definitions/label",
      "description": "label characteristics"
    },
    "notification_email": {
      "type": "string",
      "description": "email address that we should notify once there's an update for this shipment"
    },
    "additional_services": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "enum": ["advance_notice", "cash_on_delivery", "delivery_time", "dhl_ident_check", "drop_authorization", "gls_guaranteed24service", "premium_international", "saturday_delivery", "ups_adult_signature"],
            "description": "key to identify the additional service"
          },
          "properties": {
            "type": "object",
            "properties": {
              "amount": { "type": "number" },
              "bank_account_holder": { "type": "string" },
              "bank_account_number": { "type": "string" },
              "bank_code": { "type": "string" },
              "bank_name": { "type": "string" },
              "currency": { "type": "string" },
              "date_of_birth": { "type": "string" },
              "email": { "type": "string" },
              "first_name": { "type": "string" },
              "language": {
                "type": "string",
                "description": "language the customer should be notified in (ISO-639-1 format)"
              },
              "last_name": { "type": "string" },
              "minimum_age": { "type": "string" },
              "phone": { "type": "string" },
              "reference1": {
                "type": "string",
                "description": "Text that should be displayed as the reason for transfer"
              },
              "sms": { "type": "string" },
              "time_of_day_earliest": { "type": "string" },
              "time_of_day_latest": { "type": "string" }
            }
          }
        }
      },
      "required": ["name"],
      "additionalProperties": false
    },
    "pickup": {
      "$ref": "#/definitions/pickup",
      "description": "pickup request for this shipment"
    },
    "customs_declaration": {
      "type": "object",
      "description": "declaration of customs related information",
      "properties": {
        "contents_type": {
          "type": "string",
          "enum": ["commercial_goods", "commercial_sample", "documents", "gift", "returned_goods"],
          "description": "Type of contents"
        },
        "contents_explanation": {
          "type": "string",
          "description": "description of contents. Mandatory if contents_type is 'commercial_goods. Max 256 characters, when using DHL as your carrier'"
        },
        "currency": {
          "type": "string",
          "description": "a valid ISO 4217 curreny code"
        },
        "additional_fees": {
          "type": "number",
          "description": "additional custom fees to be payed"
        },
        "drop_off_location": {
          "type": "string",
          "description": "location where the package will be dropped of with the carrier"
        },
        "exporter_reference": {
          "type": "string",
          "description": "a note for the exporter"
        },
        "importer_reference": {
          "type": "string",
          "description": "a note for the importer"
        },
        "posting_date": {
          "type": "string",
          "format": "date",
          "description": "date of commital at carrier"
        },
        "invoice_number": {
          "type": "string",
          "description": "invoice number for the order"
        },
        "total_value_amount": {
          "type": "number",
          "minimum": 0,
          "maximum": 1000,
          "description": "the overall value of the shipments' contents"
        },
        "items": {
          "type": "array",
          "description": "array of item objects",
          "items": {
            "type": "object",
            "properties": {
              "origin_country": {
                "type": "string",
                "description": "Country as uppercase ISO 3166-1 alpha-2 code"
              },
              "description": {
                "type": "string",
                "description": "a description of the item"
              },
              "hs_tariff_number": {
                "type": "string",
                "description": "customs tariff number. See https://en.wikipedia.org/wiki/Harmonized_System#Tariffs_by_region for detailed information on region specific tariff numbers",
                "maxLength": 10
              },
              "quantity": {
                "type": "integer",
                "description": "Number that defines how many items of this kind are in the shipment"
              },
              "value_amount": {
                "type": "string",
                "description": "The total value for items of this kind"
              },
              "net_weight": {
                "type": "number",
                "description": "Total weight for items of this kind"
              }
            },
            "required": ["origin_country", "description", "quantity", "value_amount", "net_weight"],
            "additionalProperties": false
          }
        }
      },
      "required": ["contents_type", "currency", "total_value_amount", "items"],
      "additionalProperties": false
    },
    "create_shipping_label": {
      "type": "boolean",
      "description": "determines if a shipping label should be created at the carrier (this means you will be charged when using the production api key)"
    },
    "metadata": {
      "type": "object",
      "description": "here you can save additional data that you want to be associated with the shipment. Any combination of key-value pairs is possible",
      "additionalProperties": true
    }
  },
  "required": ["carrier", "to", "package"],
  "additionalProperties": false,
  "definitions": {
    "address": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "description": "identifier of a previously created address"
        },
        "company": { "type": "string" },
        "first_name": { "type": "string" },
        "last_name": { "type": "string" },
        "care_of": { "type": "string" },
        "street": { "type": "string" },
        "street_no": { "type": "string" },
        "city": { "type": "string" },
        "zip_code": { "type": "string" },
        "state": { "type": "string" },
        "country": { "type": "string", "description": "Country as uppercase ISO 3166-1 alpha-2 code" },
        "phone": {
          "type": "string",
          "description": "telephone number (mandatory when the following terms apply - when carrier is UPS: service is one_day or one_day_early or ship to country is different than ship from country. Carrier is DHL Express: always provide phone number.)"
        },
        "email": {
          "type": "string",
          "description": "email address of the receiver to get notified by the carrier. Currently only used when sending shipments via GLS - ShopDeliveryService"
        }
      },
      "required": ["last_name", "street", "street_no", "city", "zip_code", "country"],
      "additionalProperties": false
    },
    "label": {
      "type": "object",
      "properties": {
        "size":  {
          "type": "string",
          "enum": ["A5", "A6"],
          "description": "defines the DIN size that the returned label should have"
        }
      },
      "additionalProperties": false,
      "description": "label specific definitions"
    },
    "package": {
      "type": "object",
      "properties": {
        "width":  { "type": "number" },
        "height": { "type": "number" },
        "length": { "type": "number" },
        "weight": { "type": "number" },
        "declared_value": {
          "type": "object",
          "description": "Use this to book additional insurance or expand the liability for a shipment. Caution: Please keep in mind that additional fees are charged by the carrier.",
          "properties": {
            "amount": { "type": "number" },
            "currency": { "type": "string" }
          }
        },
        "description": {
          "type": "string",
          "description": "text that describes the contents of the package. This parameter is mandatory if you're using UPS with service 'returns' or TNT with service 'one_day' or 'one_day_early'"
        },
        "type": {
          "type": "string",
          "enum": ["books", "bulk", "letter", "parcel", "parcel_letter", "cargo_international_large_parcel"],
          "description": "defines packages of being of a certain type - if no value is given, parcel will be used"
        }
      },
      "required": ["width", "height", "length", "weight"],
      "additionalProperties": false,
      "description": "defines package dimensions"
    },
    "pickup": {
      "type": "object",
      "properties": {
        "pickup_time": {
          "type": "object",
          "properties": {
            "earliest": {
              "type": "string",
              "format": "date-time"
            },
            "latest": {
              "type": "string",
              "format": "date-time"
            }
          },
          "description": "defined time window when the carrier should pickup shipments",
          "required": ["earliest", "latest"],
          "additionalProperties": false
        },
        "pickup_address": {
          "$ref": "#/definitions/address",
          "description": "address where the shipment should be picked up"
        }
      },
      "required": ["pickup_time"],
      "additionalProperties": false
    }
  }
}

download