{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "additional_services": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "enum": ["advance_notice", "angel_de_delivery_date_time", "cash_on_delivery", "delivery_date", "delivery_note", "delivery_time", "dhl_endorsement", "dhl_gogreen", "dhl_ident_check", "dhl_named_person_only", "dhl_no_neighbor_delivery", "dhl_parcel_outlet_routing", "dhl_preferred_neighbor", "dpd_food", "drop_authorization", "gls_guaranteed24service", "hermes_identservice", "premium_international", "saturday_delivery", "ups_adult_signature", "ups_carbon_neutral", "ups_direct_delivery_only", "ups_signature_required", "visual_age_check"],
            "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": { "type": "string" },
              "date_of_birth": { "type": "string" },
              "email": { "type": "string" },
              "first_name": { "type": "string" },
              "handling": {
                "type": "string",
                "enum": [
                  "abandon",
                  "return_immediately"
                ],
                "description": "Used for dhl_endorsement. By choosing the handling option abandon, your parcel will not be returned to you, but rather auctioned off or destroyed by the recipient countrys' postal company. You will not be charged with a return fee for this option. When using the option return_immediately, the shipment will be returned to you and you will be charged for returning it."
              },
              "id_type": {
                "type": "string",
                "enum": [
                  "german_identity_card",
                  "german_passport",
                  "international_passport"
                ],
                "description": "Type of ID document that should be used for verifying a Hermes recipient"
              },
              "id_number": {
                "type": "string",
                "description": "ID number from the document"
              },
              "language": {
                "type": "string",
                "description": "language the customer should be notified in (ISO-639-1 format)"
              },
              "last_name": { "type": "string" },
              "message": { "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
    },
    "carrier": {
      "type": "string",
      "enum": ["angel_de", "cargo_international", "dhl", "dhl_express", "dpag", "dpd", "gls", "go", "hermes", "iloxx", "parcel_one", "ups"],
      "description": "acronym of the carrier"
    },
    "carrier_tracking_no": {
      "type": "string",
      "description": "the original tracking number that can be used on the carriers website"
    },
    "cover_address": {
      "$ref": "#/definitions/address",
      "description": "Overwrites the sender address on the shipping label"
    },
    "created_at": {
      "type": "date-time",
      "description": "timestamp the shipment was created"
    },
    "customs_declaration": {
      "type": "object",
      "description": "declaration of customs related information",
      "properties": {
        "additional_fees": {
          "type": "number",
          "description": "additional custom fees to be payed"
        },
        "carrier_declaration_document_url": {
          "type": "string",
          "description": "URL where you can download the customs declaration in pdf format"
        },
        "contents_explanation": {
          "type": "string",
          "description": "description of contents. Mandatory if contents_type is 'commercial_goods. Max 256 characters, when using DHL as your carrier'"
        },
        "contents_type": {
          "type": "string",
          "enum": ["commercial_goods", "commercial_sample", "documents", "gift", "returned_goods"],
          "description": "Type of contents"
        },
        "created_at": {
          "type": "date-time",
          "description": "timestamp the customs declaration has been created"
        },
        "currency": {
          "type": "string",
          "description": "a valid ISO 4217 curreny code"
        },
        "document_type": {
          "type": "string",
          "enum": ["cn_22", "cn_23"],
          "description": "Type of customs declaration document"
        },
        "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"
        },
        "id": {
          "type": "string",
          "description": "identifier of the customs declaration"
        },
        "importer_reference": {
          "type": "string",
          "description": "a note for the importer"
        },
        "invoice_number": {
          "type": "string",
          "description": "invoice number for the order"
        },
        "items": {
          "type": "array",
          "description": "array of item objects",
          "items": {
            "type": "object",
            "properties": {
              "created_at": {
                "type": "date-time",
                "description": "timestamp the item has been created"
              },
              "description": {
                "type": "string",
                "description": "a description of the item"
              },
              "gross_weight": {
                "type": "number",
                "description": "Gross weight of a single item of this kind"
              },
              "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
              },
              "net_weight": {
                "type": "number",
                "description": "Net weight of a single item of this kind"
              },
              "origin_country": {
                "type": "string",
                "description": "Country as uppercase ISO 3166-1 alpha-2 code"
              },
              "quantity": {
                "type": "integer",
                "description": "Number that defines how many items of this kind are in the shipment"
              },
              "updated_at": {
                "type": "date-time",
                "description": "timestamp the item has been updated last"
              },
              "value_amount": {
                "type": "string",
                "description": "Value of a single item of this kind"
              }
            },
            "required": ["origin_country", "description", "quantity", "value_amount", "net_weight"],
            "additionalProperties": false
          }
        },
        "posting_date": {
          "type": "string",
          "format": "date",
          "description": "date of commital at carrier"
        },
        "total_value_amount": {
          "type": "number",
          "minimum": 0,
          "maximum": 1000,
          "description": "the overall value of the shipments' contents"
        },
        "updated_at": {
          "type": "date-time",
          "description": "timestamp the customs declaration has been updated last"
        }
      },
      "required": ["contents_type", "currency", "total_value_amount", "items"],
      "additionalProperties": false
    },
    "from": {
      "$ref": "#/definitions/address",
      "description": "If missing, the default sender address (if defined in your shipcloud account) will be used"
    },
    "id": {
      "type": "string",
      "description": "the shipment id that can be used for requesting info about a shipment or tracking it"
    },
    "incoterm": {
      "type": "string",
      "enum": ["ddp", "ddp_untaxed", "dap", "dap_cleared", "ddu", "ddu_cleared"]
    },
    "label_url": {
      "type": "string",
      "description": "URL where you can download the shipping label in the requested format"
    },
    "label_voucher_url": {
      "type": "string",
      "description": "URL where you can download the label voucher"
    },
    "notification_email": {
      "type": "string",
      "description": "email address of the receiver who should be notified of a change of shipment status by shipcloud"
    },
    "packages": {
      "type": "array",
      "items": {
        "allOf": [
          {
            "$ref": "#/definitions/package"
          }
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "identifier for a single package"
          },
          "tracking_events": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "timestamp": {
                  "type": "date-time",
                  "description": "timestamp of when this event occured"
                },
                "location": {
                  "type": "string",
                  "description": "location of the package at this moment"
                },
                "status": {
                  "type": "string",
                  "enum": ["awaits_pickup_by_receiver", "canceled", "delayed", "delivered", "destroyed", "exception", "label_created", "not_delivered", "notification", "out_for_delivery", "picked_up", "transit", "unknown"],
                  "description": "Key describing the status. The initial status is 'label_created'"
                },
                "details": {
                  "type": "string",
                  "description": "message the carrier sends to describe the package status"
                }
              },
              "required": ["timestamp", "location", "status", "details"],
              "additionalProperties": false
            }
          }
        },
        "required": ["id"],
        "additionalProperties": false
      }
    },
    "pickup": {
      "type": "object",
      "description": "for some carriers a pickup has to be requested when creating a shipment",
      "properties": {
        "pickup_time": {
          "type": "object",
          "properties": {
            "earliest": {
              "type": "string",
              "format": "date-time"
            },
            "latest": {
              "type": "string",
              "format": "date-time"
            }
          },
          "description": "defines a time window in which the carrier should pickup shipments",
          "required": ["earliest", "latest"],
          "additionalProperties": false
        },
        "pickup_address": {
          "type": "object",
          "description": "address where the carrier should pick up shipments",
          "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 using UPS and the following terms apply: service is one_day or one_day_early or ship to country is different than ship from country)"
            }
          },
          "required": ["last_name", "street", "street_no", "city", "zip_code", "country"],
          "additionalProperties": false
        }
      }
    },
    "price": {
      "type": "number",
      "description": "price that we're going to charge you (exl. VAT)"
    },
    "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"
    },
    "service": {
      "type": "string",
      "enum": [],
      "description": "the service that was used for creating this shipment"
    },
    "shipper_notification_email": {
      "type": "string",
      "description": "email address of the shipper who should be notified of a change of shipment status by shipcloud"
    },
    "to": {
      "$ref": "#/definitions/address",
      "description": "the receivers address"
    },
    "tracking_url": {
      "type": "string",
      "description": "URL you can send your customers so they can track this shipment"
    }
  },
  "required": ["id", "carrier_tracking_no", "carrier", "created_at", "tracking_url", "label_url", "from", "to", "packages", "price", "reference_number", "service"],
  "additionalProperties": false,
  "definitions": {
    "address": {
      "type": "object",
      "properties": {
        "care_of": { "type": "string" },
        "city": { "type": "string" },
        "company": { "type": "string" },
        "country": { "type": "string", "description": "Country as uppercase ISO 3166-1 alpha-2 code" },
        "first_name": { "type": "string" },
        "last_name": { "type": "string" },
        "state": { "type": "string" },
        "street": { "type": "string" },
        "street_no": { "type": "string" },
        "zip_code": { "type": "string" },
        "phone": {
          "type": "string",
          "description": "telephone number (mandatory when using UPS and the following terms apply: service is one_day or one_day_early or ship to country is different than ship from country)"
        }
      },
      "required": ["last_name", "street", "street_no", "city", "zip_code", "country"],
      "additionalProperties": false
    },
    "package": {
      "type": "object",
      "properties": {
        "height": { "type": "number" },
        "length": { "type": "number" },
        "weight": { "type": "number" },
        "width":  { "type": "number" }
      },
      "required": ["width", "height", "length", "weight"],
      "additionalProperties": false,
      "description": "defines package dimensions"
    }
  }
}

download