{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/shipcloud/main/json-schema/shipcloud-shipment-schema.json",
  "title": "shipment",
  "x-generated": "2026-10-09",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/shipcloud-openapi.yml#/components/schemas/shipment",
  "type": "object",
  "properties": {
    "carrier": {
      "$ref": "#/$defs/carrier_shipping"
    },
    "to": {
      "allOf": [
        {
          "$ref": "#/$defs/address"
        },
        {
          "anyOf": [
            {
              "type": "object",
              "properties": {
                "company": {
                  "type": "string",
                  "description": "name of the company"
                }
              },
              "required": [
                "company"
              ]
            },
            {
              "type": "object",
              "properties": {
                "last_name": {
                  "type": "string",
                  "description": "last_name of the person"
                }
              },
              "required": [
                "last_name"
              ]
            }
          ]
        },
        {
          "description": "the receivers address"
        }
      ]
    },
    "from": {
      "allOf": [
        {
          "$ref": "#/$defs/address"
        },
        {
          "anyOf": [
            {
              "type": "object",
              "properties": {
                "company": {
                  "type": "string",
                  "description": "name of the company"
                }
              },
              "required": [
                "company"
              ]
            },
            {
              "type": "object",
              "properties": {
                "last_name": {
                  "type": "string",
                  "description": "last_name of the person"
                }
              },
              "required": [
                "last_name"
              ]
            }
          ]
        },
        {
          "description": "If missing, the default sender address (if defined in your shipcloud account) will be used"
        }
      ]
    },
    "cover_address": {
      "allOf": [
        {
          "$ref": "#/$defs/address"
        },
        {
          "description": "Overwrites the sender address on the shipping label",
          "required": [
            "street",
            "street_no",
            "zip_code",
            "city"
          ]
        }
      ]
    },
    "service": {
      "$ref": "#/$defs/service"
    },
    "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": "#/$defs/label"
    },
    "notification_email": {
      "type": "string",
      "description": "email address that we should notify once there's an update for this shipment (usually the recipients')"
    },
    "incoterm": {
      "type": "string",
      "enum": [
        "ddp",
        "ddp_untaxed",
        "dap",
        "dap_cleared",
        "ddu",
        "ddu_cleared"
      ]
    },
    "billing": {
      "type": "object",
      "properties": {
        "transportation": {
          "type": "object",
          "description": "Determines, who will pay for transportation. This is applicable for domestic and international shipments",
          "properties": {
            "type": {
              "type": "string",
              "description": "Providing the key that will determine, who will pay for transportation",
              "enum": [
                "receiver",
                "sender",
                "third_party"
              ]
            },
            "account_number": {
              "type": "string",
              "description": "The account number that will be billed"
            },
            "zip_code": {
              "type": "string",
              "description": "The zip code / postalcode associated with the provided account number"
            },
            "country": {
              "type": "string",
              "description": "The country code associated with the provided account number"
            }
          },
          "required": [
            "type"
          ]
        },
        "duties_and_taxes": {
          "type": "object",
          "description": "Determines, who will pay for duties and taxes. This is only applicable for international shipments",
          "properties": {
            "type": {
              "type": "string",
              "description": "Providing the key that will determine, who will pay for duties and taxes",
              "enum": [
                "receiver",
                "sender",
                "third_party"
              ]
            },
            "account_number": {
              "type": "string",
              "description": "The account number that will be billed"
            },
            "zip_code": {
              "type": "string",
              "description": "The zip code / postalcode associated with the provided account number"
            },
            "country": {
              "type": "string",
              "description": "The country code associated with the provided account number"
            }
          },
          "required": [
            "type"
          ]
        }
      }
    },
    "additional_services": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "enum": [
              "advance_notice",
              "angel_de_delivery_date_time",
              "asendia_bonus_tracking",
              "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",
              "hazardous_goods",
              "hermes_identservice",
              "hermes_next_day",
              "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",
                "description": "Amount that should be payed (cash_on_delivery)"
              },
              "bank_account_holder": {
                "type": "string",
                "description": "Name of the person the bank account belongs to (cash_on_delivery)"
              },
              "bank_account_number": {
                "type": "string",
                "description": "IBAN (cash_on_delivery)"
              },
              "bank_code": {
                "type": "string",
                "description": "BIC/SWIFT (cash_on_delivery)"
              },
              "bank_name": {
                "type": "string",
                "description": "Name of the bank (cash_on_delivery)"
              },
              "currency": {
                "type": "string",
                "description": "Currency as uppercase ISO 4217 code (cash_on_delivery)"
              },
              "date": {
                "type": "string",
                "format": "date",
                "description": "Date (angel_de_delivery_date_time, delivery_date"
              },
              "date_of_birth": {
                "type": "string",
                "format": "date",
                "description": "A recipients date of birth (dhl_ident_check)"
              },
              "email": {
                "type": "string",
                "format": "email",
                "description": "eMail address (advanced_notice)"
              },
              "first_name": {
                "type": "string",
                "description": "The persons first name (dhl_ident_check)"
              },
              "id_type": {
                "type": "string",
                "enum": [
                  "german_identity_card",
                  "german_passport",
                  "international_passport"
                ],
                "description": "Type of ID document that should be used for verifying (hermes_ident_check)"
              },
              "id_number": {
                "type": "string",
                "description": "Number of the ID document (hermes_ident_check)"
              },
              "language": {
                "type": "string",
                "description": "Language (in ISO-639-1 format) the customer should be notified in (advanced_notice)"
              },
              "last_name": {
                "type": "string",
                "description": "The persons last name (dhl_ident_check)"
              },
              "minimum_age": {
                "type": "string",
                "description": "Minimum age that should be checked (dhl_ident_check, visual_age_check)"
              },
              "phone": {
                "type": "string",
                "description": "Phone number that can be called for making the delivery (advanced_notice)"
              },
              "reference1": {
                "type": "string",
                "description": "Text that should be displayed as the reason for transfer (cash_on_delivery)"
              },
              "sms": {
                "type": "string",
                "description": "Phone number that can be texted for making the delivery (advanced_notice)"
              },
              "time_of_day_earliest": {
                "type": "string",
                "description": "Earliest pickup date and time (angel_de_delivery_date_time)"
              },
              "time_of_day_latest": {
                "type": "string",
                "description": "Latest pickup date and time(angel_de_delivery_date_time)"
              }
            }
          }
        }
      },
      "required": [
        "name"
      ]
    },
    "pickup": {
      "$ref": "#/$defs/pickup"
    },
    "customs_declaration": {
      "$ref": "#/$defs/customs_declaration"
    },
    "order_id": {
      "type": "string",
      "description": "Identifier of a previously created order."
    },
    "returned_items": {
      "type": "array",
      "description": "List of items that get returned with this shipment",
      "items": {
        "type": "object",
        "properties": {
          "order_line_item_id": {
            "type": "string",
            "description": "UUID of the corresponding order line item within an order"
          },
          "quantity": {
            "type": "number",
            "description": "Number that defines how many items of this kind are in the shipment"
          },
          "reason_for_return": {
            "type": "string",
            "description": "A key that represents the reason why the item(s) will be returned",
            "enum": [
              "delivery_too_late",
              "delivery_wrong_product",
              "garment_expectation_failed_style",
              "garment_too_large",
              "garment_too_long",
              "garment_too_short",
              "garment_too_small",
              "ordered_choices",
              "other",
              "product_description_differing",
              "product_expectation_failed_color",
              "product_expectation_failed_material",
              "product_expectation_failed_price",
              "product_faulty"
            ]
          }
        }
      }
    },
    "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"
    }
  },
  "required": [
    "carrier",
    "to"
  ],
  "$defs": {
    "address": {
      "type": "object",
      "properties": {
        "care_of": {
          "type": [
            "string",
            "null"
          ],
          "description": "Additional care of field"
        },
        "city": {
          "type": "string",
          "description": "Name of the city"
        },
        "country": {
          "type": "string",
          "description": "Country as uppercase ISO 3166-1 alpha-2 code"
        },
        "first_name": {
          "type": [
            "string",
            "null"
          ],
          "description": "A persons first name"
        },
        "state": {
          "type": [
            "string",
            "null"
          ],
          "description": "The state the address is in"
        },
        "street": {
          "type": "string",
          "description": "Name of the street. Can hold the house number"
        },
        "street_no": {
          "type": [
            "string",
            "null"
          ],
          "description": "House number of the address (when a carrier requires it separately)"
        },
        "zip_code": {
          "type": "string",
          "description": "Zipcode of the address"
        },
        "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)"
        },
        "email": {
          "type": "string",
          "description": "Email address for this person. Some carrier are using the email address to send notifications"
        }
      },
      "required": [
        "street",
        "city",
        "zip_code",
        "country"
      ]
    },
    "address_with_id": {
      "allOf": [
        {
          "$ref": "#/$defs/address"
        },
        {
          "type": "object",
          "properties": {
            "id": {
              "type": "string",
              "description": "identifier of a previously created address"
            }
          },
          "required": [
            "id",
            "first_name",
            "last_name",
            "company",
            "care_of",
            "state",
            "street_no"
          ]
        }
      ]
    },
    "carrier_shipping": {
      "type": "string",
      "enum": [
        "angel_de",
        "asendia",
        "cargo_international",
        "dhl",
        "dhl_express",
        "dpag",
        "dpd",
        "gls",
        "go",
        "hermes",
        "iloxx",
        "parcel_one",
        "ups"
      ],
      "description": "acronym of the carrier"
    },
    "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"
        },
        "movement_reference_number": {
          "type": "string",
          "description": "the movement reference number (MRN)"
        },
        "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"
        }
      },
      "required": [
        "contents_type",
        "currency",
        "total_value_amount",
        "items"
      ]
    },
    "label": {
      "type": "object",
      "properties": {
        "format": {
          "type": "string",
          "enum": [
            "pdf_100x70mm",
            "pdf_103x199mm",
            "pdf_a5",
            "pdf_a6",
            "pdf_a7",
            "zpl2_4x6in_203dpi",
            "zpl2_4x6in_300dpi",
            "zpl2_100x70mm_203dpi",
            "zpl2_103x199mm_203dpi"
          ],
          "description": "defines the format that the returned label should have"
        },
        "size": {
          "type": "string",
          "enum": [
            "A5",
            "A6",
            "A7",
            "100x70mm"
          ],
          "description": "defines the size that the returned label should have",
          "deprecated": true
        }
      },
      "description": "label specific definitions"
    },
    "pickup": {
      "type": "object",
      "description": "for some carriers a pickup has to be requested when creating a shipment",
      "properties": {
        "pickup_time": {
          "$ref": "#/$defs/pickup_time_object"
        },
        "pickup_address": {
          "$ref": "#/$defs/address_with_id"
        }
      }
    },
    "pickup_time_object": {
      "type": "object",
      "properties": {
        "earliest": {
          "type": "string",
          "format": "date-time",
          "description": "Earliest pickup date and time"
        },
        "latest": {
          "type": "string",
          "format": "date-time",
          "description": "Latest pickup date and time"
        }
      },
      "description": "defines a time window in which the carrier should pickup shipments",
      "required": [
        "earliest",
        "latest"
      ]
    },
    "service": {
      "type": "string",
      "enum": [
        "standard",
        "one_day",
        "one_day_early",
        "returns",
        "asendia_epaq_standard_economy",
        "asendia_epaq_standard_priority",
        "cargo_international_express",
        "dhl_europaket",
        "dhl_prio",
        "dhl_warenpost",
        "dpag_warenpost",
        "dpag_warenpost_signature",
        "dpag_warenpost_untracked",
        "gls_express_0800",
        "gls_express_0900",
        "gls_express_1000",
        "gls_express_1200",
        "ups_express_1200"
      ],
      "default": "standard",
      "description": "The service that should be used for the shipment."
    }
  }
}