{ "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://raw.githubusercontent.com/api-evangelist/shipcloud/main/json-schema/shipcloud-shipment-response-object-schema.json", "title": "shipment_response_object", "x-generated": "2026-10-09", "x-method": "derived", "x-generator": "derive-json-schema.py", "x-source": "openapi/shipcloud-openapi.yml#/components/schemas/shipment_response_object", "allOf": [ { "$ref": "#/$defs/shipment" }, { "type": "object", "properties": { "to": { "$ref": "#/$defs/address_with_id" }, "from": { "$ref": "#/$defs/address_with_id" } } }, { "type": "object", "properties": { "id": { "type": "string", "description": "identifier of the shipment" }, "carrier_tracking_no": { "type": "string", "description": "the original tracking number that can be used on the carriers website" }, "carrier_tracking_url": { "type": "string", "description": "the original tracking URL of the carrier" }, "created_at": { "type": "string", "format": "date-time", "description": "timestamp the shipment was created" }, "label_url": { "type": "string", "description": "URL where you can download the label in pdf format" }, "packages": { "type": "array", "items": { "allOf": [ { "$ref": "#/$defs/package_with_id" } ] } }, "price": { "type": "number", "description": "price that we're going to charge you (exl. VAT)" }, "shipper_notification_email": { "type": "string", "description": "email address of the shipper who should be notified of a change of shipment status by shipcloud" }, "tracking_url": { "type": "string", "description": "URL you can send your customers so they can track this shipment" }, "customs_declaration": { "$ref": "#/$defs/customs_declaration_response" } }, "required": [ "id", "carrier", "created_at", "tracking_url", "from", "to", "packages", "price", "service" ] } ], "$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" ] }, "customs_declaration_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 net weight for a single item of this kind" }, "gross_weight": { "type": "number", "description": "Total gross weight for a single item of this kind" } }, "required": [ "origin_country", "description", "quantity", "value_amount", "net_weight" ] }, "customs_declaration_response": { "allOf": [ { "$ref": "#/$defs/customs_declaration" }, { "type": "object", "properties": { "created_at": { "type": "string", "format": "date-time", "description": "timestamp of when the customs declaration was created" }, "updated_at": { "type": "string", "format": "date-time", "description": "timestamp of when the customs declaration was last updated" }, "carrier_declaration_document_url": { "type": "string", "format": "uri", "description": "A URL that points to the customs declaration document" }, "items": { "type": "array", "items": { "allOf": [ { "$ref": "#/$defs/customs_declaration_items" }, { "type": "object", "properties": { "id": { "type": "string", "description": "A unique identifier for this item" }, "created_at": { "type": "string", "format": "date-time", "description": "timestamp of when the item was created" }, "updated_at": { "type": "string", "format": "date-time", "description": "timestamp of when the item was last updated" } }, "required": [ "id", "created_at", "updated_at" ] } ] } } } } ] }, "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" }, "package_minimal": { "type": "object", "properties": { "height": { "type": "number", "description": "Height of the parcel in cm" }, "length": { "type": "number", "description": "Length of the parcel in cm" }, "weight": { "type": "number", "description": "Weight of the parcel in kg" }, "width": { "type": "number", "description": "Width of the parcel in cm" } }, "required": [ "width", "height", "length", "weight" ], "description": "defines package attributes" }, "package_response_object": { "allOf": [ { "$ref": "#/$defs/package_minimal" }, { "properties": { "declared_value": { "type": "object", "description": "Object that is used for booking an additional insurance at the carrier (if applicable)", "properties": { "amount": { "type": "number", "description": "The total amount of the goods value that an additional insurance should be booked for" }, "currency": { "type": "string", "description": "The currency used. Currently only EUR is applicable" } } }, "description": { "type": "string", "description": "if you're using UPS with service `returns` this is mandatory otherwise it's optional" }, "type": { "type": "string", "description": "type of shipment you would like to book", "enum": [ "books", "bulk", "letter", "parcel", "parcel_letter" ], "default": "parcel" } } } ] }, "package_with_id": { "allOf": [ { "$ref": "#/$defs/package_response_object" }, { "properties": { "id": { "type": "string", "description": "A unique identifier for this package" }, "tracking_events": { "type": "array", "items": { "type": "object", "properties": { "timestamp": { "type": "string", "format": "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": "A key that is describing the status" }, "details": { "type": "string", "description": "Message the carrier sent to describe the package status" } }, "required": [ "timestamp", "location", "status", "details" ] } } }, "required": [ "id" ] } ] }, "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." }, "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" ] } } }