shipment_response_object

{
  "$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"
      ]
    }
  }
}