Properties
| Name | Type | Description |
|---|---|---|
| carrier | object | |
| to | object | |
| from | object | |
| cover_address | object | |
| service | object | |
| reference_number | string | 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 | string | 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 countrie |
| label | object | |
| notification_email | string | email address that we should notify once there's an update for this shipment (usually the recipients') |
| incoterm | string | |
| billing | object | |
| additional_services | array | |
| pickup | object | |
| customs_declaration | object | |
| order_id | string | Identifier of a previously created order. |
| returned_items | array | List of items that get returned with this shipment |
| create_shipping_label | boolean | determines if a shipping label should be created at the carrier (this means you will be charged when using the production api key) |
| metadata | object | here you can save additional data that you want to be associated with the shipment. Any combination of key-value pairs is possible |
JSON Schema
{
"$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."
}
}
}Work with this as data
Every JSON Schema here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for schemas
4 MCP tools reach this
find_json_schemasBrowse and filter every JSON Schema in the catalog.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This JSON Schema
curl "https://apis.io/api/v1/json-schemas/shipcloud-shipment"
All schemas
curl "https://apis.io/api/v1/json-schemas?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.