> ## Documentation Index > Fetch the complete documentation index at: https://sendcloud.dev/llms.txt > Use this file to discover all available pages before exploring further. # Create and announce a shipment asynchronously > This endpoint **announces a shipment asynchronously** under your API credentials. ## International shipments If you want to create a shipment to be sent to a destination country outside the EU, it's mandatory to include additional information related to the shipment contents. This allows Sendcloud to automatically generate the required customs documentation based on the international shipping option selected. After the shipping label and associated documents are generated, you can retrieve and download them via the [Retrieve a parcel document](/api/v3/parcel-documents/retrieve-a-parcel-document) endpoint. Note that when passing along prices, mixed currencies are not accepted. Therefore, ensure that all price fields use the same currency. ## Multicollo Learn more about multicollo in our [Multicollo guide](/docs/shipping/multicollo). ## OpenAPI ````yaml /.openapi/v3/shipments/openapi.yaml post /shipments openapi: 3.1.0 info: title: Shipments version: 3.0.0 description: >- The Shipments API allows you to create and announce, retrieve, and cancel outgoing shipments and their associated parcels within the Sendcloud platform. contact: name: Sendcloud API Support email: contact@sendcloud.com license: name: Apache 2.0 url: https://www.apache.org/licenses/LICENSE-2.0.html servers: - url: https://panel.sendcloud.sc/api/v3 description: Sendcloud Production security: [] tags: - name: Shipments description: Shipments API paths: /shipments: post: tags: - Shipments summary: Create and announce a shipment asynchronously description: >- This endpoint **announces a shipment asynchronously** under your API credentials. operationId: sc-public-v3-scp-post-create_shipment parameters: - $ref: '#/components/parameters/SendcloudPartnerId' requestBody: content: application/json: schema: $ref: '#/components/schemas/shipment-request-async' examples: CreateDomesticSingleParcelShipment: summary: Create a domestic shipment (with a single parcel) value: to_address: name: John Doe company_name: Sendcloud address_line_1: Insulindelaan 115 house_number: '115' postal_code: 5642CV city: Eindhoven country_code: NL phone_number: '+31612345678' email: john.doe@sendcloud.com po_box: PO Box 678 from_address: name: Marie Doe company_name: Sendcloud address_line_1: Stadhuisplein 10 address_line_2: 2e verdieping house_number: '10' postal_code: 5611 EM city: Eindhoven country_code: NL phone_number: '+31612345678' email: marie.doe@sendcloud.com po_box: PO Box 478 ship_with: type: shipping_option_code properties: shipping_option_code: postnl:standard contract_id: 517 order_number: '1234567890' total_order_price: currency: EUR value: '11.11' parcels: - dimensions: length: '5.00' width: '15.00' height: '20.00' unit: cm weight: value: '1.320' unit: kg parcel_items: - item_id: '5552' description: T-Shirt XL quantity: 1 weight: value: 0.3 unit: kg price: value: '12.65' currency: EUR hs_code: '620520' origin_country: NL sku: TS1234 product_id: '19284' mid_code: NLOZR92MEL material_content: 100% Cotton intended_use: Personal use dds_reference: 25FIYPEK0A7573 taric_doc_code: Y142 properties: size: XL color: green - item_id: '98712' description: Sneakers 42 quantity: 1 weight: value: 1.02 unit: kg price: value: '12.65' currency: EUR hs_code: '620520' origin_country: US sku: TS1234 product_id: '19284' mid_code: US1234567 material_content: 100% Cotton intended_use: Personal use dds_reference: 25FIYPEK0A7573 taric_doc_code: Y142 properties: size: 42 color: black CreateCustomsRequiredShipment: summary: Create a shipment (with a single parcel) that requires customs value: to_address: name: John Doe company_name: Company XYZ address_line_1: 123 West 43rd St postal_code: '10036' city: New York country_code: US phone_number: '+12129976661' email: john.doe@sendcloud.com state_province_code: US-NY po_box: PO Box 678 from_address: name: Marie Doe company_name: Sendcloud address_line_1: Stadhuisplein 10 address_line_2: 2e verdieping house_number: '10' postal_code: 5611 EM city: Eindhoven country_code: NL phone_number: '+31612345678' email: marie.doe@sendcloud.com po_box: PO Box 478 ship_with: type: shipping_option_code properties: shipping_option_code: dhl_express:worldwide/incoterm=dap contract_id: 4195 order_number: '1234567890' total_order_price: currency: EUR value: '11.11' parcels: - dimensions: length: '5.00' width: '15.00' height: '20.00' unit: cm weight: value: '1.320' unit: kg parcel_items: - item_id: '5552' description: T-Shirt XL quantity: 1 weight: value: 0.3 unit: kg price: value: '12.65' currency: EUR hs_code: '620520' origin_country: NL sku: TS1234 product_id: '19284' mid_code: NLOZR92MEL material_content: 100% Cotton intended_use: Personal use dds_reference: 25FIYPEK0A7573 taric_doc_code: Y142 properties: size: XL color: green - item_id: '98712' description: Sneakers 42 quantity: 1 weight: value: 1.02 unit: kg price: value: '12.65' currency: EUR hs_code: '620520' origin_country: US sku: TS1234 product_id: '19284' mid_code: US1234567 material_content: 100% Cotton intended_use: Personal use dds_reference: 25FIYPEK0A7573 taric_doc_code: Y142 properties: size: 42 color: black customs_information: invoice_number: INV-123 export_reason: commercial_goods export_type: private invoice_date: '2023-08-24' discount_granted: value: '14.99' currency: EUR freight_costs: value: '21.98' currency: EUR insurance_costs: value: '3.60' currency: EUR other_costs: value: '1.2' currency: EUR goods_description: Electronic components and accessories general_notes: >- Compliance: Goods comply with international safety standards (CE certified). additional_declaration_statements: - >- With reference to the above shipment, I understate that the content is not made of leather parts of animal species protected by the Washington Convention. - >- I solemnly declare that the contents of this document represent a true and accurate account of the events as they occurred. I acknowledge my responsibility for the information presented herein and understand that any misrepresentation or falsification may result in legal consequences or other penalties as applicable. importer_of_record: name: John Doe company_name: Company XYZ address_line_1: 123 West 43rd St postal_code: '10036' city: New York country_code: US state_province_code: US-NY telephone: '+12129976661' email: john.doe@sendcloud.com tax_numbers: sender: - name: VAT country_code: NL value: NL123456789B01 - name: EORI country_code: NL value: NL123456789 receiver: - name: EIN country_code: US value: '123456789' importer_of_record: - name: EIN country_code: US value: '123456789' CreateDomesticMulticolloShipment: summary: Create a multicollo domestic shipment value: from_address: address_line_1: Stadhuisplein 10 address_line_2: 2e verdieping city: Eindhoven company_name: Sendcloud country_code: NL email: marie.doe@sendcloud.com house_number: '10' name: Marie Doe phone_number: '+31612345678' postal_code: 5611 EM po_box: PO Box 678 to_address: address_line_1: Stadhuisplein 10 address_line_2: 2e verdieping city: Rotterdam company_name: Sendcloud country_code: NL email: marie.doe@sendcloud.com house_number: '10' name: Marie Doe phone_number: '+31612345678' postal_code: 3029 AD po_box: PO Box 679 ship_with: type: shipping_option_code properties: shipping_option_code: dpd:home order_number: '1234567890' total_order_price: currency: EUR value: '11.11' parcels: - dimensions: length: '5.00' width: '15.00' height: '20.00' unit: cm weight: value: '1.320' unit: kg parcel_items: - item_id: '5552' description: T-Shirt XL quantity: 1 weight: value: 0.3 unit: kg price: value: '10.65' currency: EUR hs_code: '12345678' origin_country: NL sku: TS1234 product_id: '19284' mid_code: NLOZR92MEL material_content: 100% Cotton intended_use: Personal use dds_reference: 25FIYPEK0A7573 taric_doc_code: Y142 properties: size: XL color: green - dimensions: length: '10.00' width: '20.00' height: '30.00' unit: cm weight: value: '2.320' unit: kg parcel_items: - item_id: '5552' description: T-Shirt L quantity: 1 weight: value: 0.3 unit: kg price: value: '7.65' currency: EUR hs_code: '12345677' origin_country: NL sku: TS1235 product_id: '19284' mid_code: NLOZR92MEL material_content: 100% Cotton intended_use: Personal use dds_reference: 25FIYPEK0A7573 taric_doc_code: Y142 properties: size: XL color: green description: '' responses: '201': description: OK content: application/json: schema: description: Create a shipment type: object title: Shipment created response properties: data: $ref: '#/components/schemas/shipment-response' examples: CreatedDomesticSingleParcelShipment: summary: Domestic Shipment (with a single parcel) created value: data: id: XXX-Shipment-id order_number: '1234567890' total_order_price: currency: EUR value: '11.11' parcels: - status: code: ANNOUNCING message: Being announced documents: [] dimensions: width: '15.00' length: '5.00' height: '20.00' unit: cm weight: value: '1.320' unit: kg tracking_url: null tracking_number: '' additional_carrier_data: awb_tracking_number: null box_number: null created_at: '2024-06-06T17:11:14.616615Z' updated_at: '2024-06-06T17:11:14.648081Z' announced_at: null parcel_items: - item_id: '5552' description: T-Shirt XL quantity: 1 weight: value: 0.3 unit: kg price: value: '12.65' currency: EUR hs_code: '620520' origin_country: NL sku: TS1234 product_id: '19284' mid_code: NLOZR92MEL material_content: 100% Cotton intended_use: Personal use dds_reference: 25FIYPEK0A7573 taric_doc_code: Y142 properties: size: XL color: green - item_id: '98712' description: Sneakers 42 quantity: 1 weight: value: 1.02 unit: kg price: value: '12.65' currency: EUR hs_code: '620520' origin_country: US sku: TS1234 product_id: '19284' mid_code: US1234567 material_content: 100% Cotton intended_use: Personal use dds_reference: 25FIYPEK0A7573 taric_doc_code: Y142 properties: size: 42 color: black from_address: address_line_1: Stadhuisplein 10 address_line_2: 2e verdieping city: Eindhoven company_name: Sendcloud country_code: NL email: marie.doe@sendcloud.com house_number: '10' name: Marie Doe phone_number: '+31612345678' postal_code: 5611 EM po_box: PO Box 678 to_address: address_line_1: Insulindelaan address_line_2: '' city: Eindhoven company_name: Sendcloud country_code: NL email: john.doe@sendcloud.com house_number: '115' name: John Doe phone_number: '+31612345678' postal_code: 5642 CV po_box: PO Box 478 ship_with: type: shipping_option_code properties: shipping_option_code: postnl:standard contract_id: 517 customs_information: null carrier: code: postnl name: PostNL errors: [] CreatedCustomsRequiredShipment: summary: Shipment (with Customs and a single parcel) created value: data: id: XXX-Shipment-id order_number: '1234567890' total_order_price: currency: EUR value: '11.11' parcels: - id: 383707309 status: code: ANNOUNCING message: Being announced documents: [] dimensions: width: '15.00' length: '5.00' height: '20.00' unit: cm weight: value: '1.320' unit: kg tracking_url: null tracking_number: '' additional_carrier_data: awb_tracking_number: null box_number: null created_at: '2024-06-06T17:11:14.616615Z' updated_at: '2024-06-06T17:11:14.648081Z' announced_at: null parcel_items: - item_id: '5552' description: T-Shirt XL quantity: 1 weight: value: 0.3 unit: kg price: value: '12.65' currency: EUR hs_code: '620520' origin_country: NL sku: TS1234 product_id: '19284' mid_code: NLOZR92MEL material_content: 100% Cotton intended_use: Personal use dds_reference: 25FIYPEK0A7573 taric_doc_code: Y142 properties: size: XL color: green - item_id: '98712' description: Sneakers 42 quantity: 1 weight: value: 1.02 unit: kg price: value: '12.65' currency: EUR hs_code: '620520' origin_country: US sku: TS1234 product_id: '19284' mid_code: US1234567 material_content: 100% Cotton intended_use: Personal use dds_reference: 25FIYPEK0A7573 taric_doc_code: Y142 properties: size: 42 color: black from_address: address_line_1: Stadhuisplein 10 address_line_2: 2e verdieping city: Eindhoven company_name: Sendcloud country_code: NL email: marie.doe@sendcloud.com house_number: '10' name: Marie Doe phone_number: '+31612345678' postal_code: 5611 EM po_box: PO Box 678 to_address: name: John Doe company_name: Company XYZ address_line_1: 10 Kamal Chunchie Way address_line_2: '' postal_code: E16 1ZE city: London country_code: GB phone_number: '+31612345678' email: john.doe@sendcloud.com state_province_code: GB-ENG po_box: PO Box 678 ship_with: type: shipping_option_code properties: shipping_option_code: dhl_express:worldwide/incoterm=dap contract_id: 4195 customs_information: invoice_number: INV-123 export_reason: commercial_goods export_type: private invoice_date: '2023-08-24' discount_granted: value: '14.99' currency: EUR freight_costs: value: '21.98' currency: EUR insurance_costs: value: '3.60' currency: EUR other_costs: value: '1.2' currency: EUR goods_description: Electronic components and accessories general_notes: >- Compliance: Goods comply with international safety standards (CE certified). additional_declaration_statements: - >- With reference to the above shipment, I understate that the content is not made of leather parts of animal species protected by the Washington Convention. - >- I solemnly declare that the contents of this document represent a true and accurate account of the events as they occurred. I acknowledge my responsibility for the information presented herein and understand that any misrepresentation or falsification may result in legal consequences or other penalties as applicable. importer_of_record: name: John Doe company_name: ImporterCo address_line_1: Maple Avenue address_line_2: '' house_number: '123' postal_code: '90210' city: Springfield country_code: US state_province_code: US-MA telephone: '+15551234567' email: info@importer-of-record-example.com tax_numbers: sender: - name: VAT country_code: NL value: NL123456789B01 - name: EORI country_code: NL value: NL123456789 receiver: - name: EIN country_code: US value: '123456789' importer_of_record: - name: EIN country_code: US value: '987654321' carrier: code: postnl name: PostNL errors: [] CreatedDomesticMulticolloShipment: summary: Domestic Multicollo Shipment created value: data: id: 1ec27105-ca61-49f2-85d8-55952f714b8d ship_with: type: shipping_option_code properties: shipping_option_code: dpd:home contract_id: 52024 from_address: name: Marie Doe company_name: Sendcloud address_line_1: Stadhuisplein 10 house_number: '10' address_line_2: 2e verdieping postal_code: 5611 EM city: Eindhoven po_box: null state_province_code: null country_code: NL email: marie.doe@sendcloud.com phone_number: '+31612345678' to_address: name: Marie Doe company_name: Sendcloud address_line_1: Stadhuisplein house_number: '10' address_line_2: 2e verdieping postal_code: 3029 AD city: Rotterdam po_box: PO Box 679 state_province_code: null country_code: NL email: marie.doe@sendcloud.com phone_number: '+31612345678' to_service_point: null customs_information: null parcels: - parcel_items: - origin_country: NL hs_code: '12345678' price: value: '10.65' currency: EUR weight: value: 0.3 unit: kg description: T-Shirt XL quantity: 1 product_id: '19284' mid_code: NLOZR92MEL material_content: 100% Cotton intended_use: Personal use dds_reference: 25FIYPEK0A7573 taric_doc_code: Y142 item_id: '5552' properties: size: XL color: green sku: TS1234 dimensions: width: '15.00' length: '5.00' height: '20.00' unit: cm weight: value: '1.320' unit: kg created_at: '2024-10-30T14:02:30.844592Z' updated_at: '2024-10-30T14:02:30.888261Z' announced_at: null id: 427189741 status: code: ANNOUNCING message: Being announced documents: [] tracking_number: '' tracking_url: null additional_carrier_data: awb_tracking_number: null box_number: null label_file: null - parcel_items: - origin_country: NL hs_code: '12345677' price: value: '7.65' currency: EUR weight: value: 0.3 unit: kg description: T-Shirt L quantity: 1 product_id: '19284' mid_code: NLOZR92MEL material_content: 100% Cotton intended_use: Personal use dds_reference: 25FIYPEK0A7573 taric_doc_code: Y142 item_id: '5552' properties: size: XL color: green sku: TS1235 dimensions: width: '20.00' length: '10.00' height: '30.00' unit: cm weight: value: '2.320' unit: kg created_at: '2024-10-30T14:02:30.844592Z' updated_at: '2024-10-30T14:02:30.844592Z' announced_at: null id: 427189742 status: code: ANNOUNCING message: Being announced documents: [] tracking_number: '' tracking_url: null additional_carrier_data: awb_tracking_number: null box_number: null label_file: null order_number: '1234567890' total_order_price: value: '11.11' currency: EUR brand_id: null carrier: code: postnl name: PostNL errors: [] '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/errors' examples: Failed: summary: Failed to create shipment (with a single parcel) value: errors: - detail: This field is required. status: '400' source: pointer: /data/attributes/to_address/name code: required '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/errors' examples: NotFound: summary: Partner ID was not found. value: errors: - title: Not found detail: The partner ID was not found. status: '404' code: not_found security: - HTTPBasicAuth: [] - OAuth2ClientCreds: [] components: parameters: SendcloudPartnerId: in: header name: Sendcloud-Partner-Id description: >- If you are an official [Sendcloud Tech Partner](https://www.sendcloud.com/ecosystem/), send your unique Sendcloud Partner UUID as a request header for the system to recognize you. The header is not required but if it is set, the system will check it. An unknown or invalid UUID will cause a 400 error. schema: type: string schemas: shipment-request-async: title: Asynchronous Announcement Shipment request Object description: Asynchronous Shipment request object model type: object allOf: - $ref: '#/components/schemas/shipment-request' - $ref: '#/components/schemas/multicollo-parcels-array-request' - required: - parcels shipment-response: title: Shipment response Object description: Shipment response object model type: object allOf: - $ref: '#/components/schemas/base-shipment-response' - type: object properties: parcels: description: Represent each package of the shipment. type: array items: $ref: '#/components/schemas/parcels-array-response' errors: title: Errors description: >- A standardized format for errors in [JSON:API](https://jsonapi.org/format/#error-objects) responses. type: array items: allOf: - $ref: '#/components/schemas/ErrorObject' - required: - status - code - detail shipment-request: title: Shipment request Object description: Shipment request object model allOf: - $ref: '#/components/schemas/shipment-common' - type: object required: - from_address properties: from_address: description: >- The sender address for the shipment. You can either provide a `sender_address_id` to reference a pre-configured sender address (with optional address field overrides), or provide all address fields directly. oneOf: - $ref: '#/components/schemas/address-with-sender-address-id' - $ref: '#/components/schemas/address-with-required-fields' to_service_point: $ref: '#/components/schemas/service-point-request' label_details: $ref: '#/components/schemas/label-details' delivery_dates: oneOf: - $ref: '#/components/schemas/delivery-dates' - type: 'null' description: >- Defined delivery dates. The `handover_at` date indicates when the item will be handed over to the carrier by the merchant in ISO 8601. If this date is not passed the carrier default will be used. For most carriers this is the following working day. type: object multicollo-parcels-array-request: title: Multicollo parcels array Object description: Multicollo parcels array model type: object properties: parcels: description: >- Represent each package of the shipment. There is a restriction to a maximum number of percels per shipment. * **sync** announcements : max 15 parcels per shipment * **async** announcements: max 50 parcels per shipment Note: each carrier can have a lower than the max number of parcels limit per shipment. type: array items: $ref: '#/components/schemas/parcel-common' minItems: 1 maxItems: 50 base-shipment-response: title: Base shipment response Object description: Base shipment response object model type: object allOf: - $ref: '#/components/schemas/shipment-common' - type: object required: - from_address properties: from_address: $ref: '#/components/schemas/address-with-required-fields' description: The sender address for the shipment. id: description: >- ID of the shipment (required to retrieve or cancel a specific shipment) type: string readOnly: true to_service_point: $ref: '#/components/schemas/service-point-response' errors: type: array items: $ref: '#/components/schemas/ErrorObject' readOnly: true description: >- This errors object will contain errors such as carrier announcement errors or validation errors. delivery-dates: $ref: '#/components/schemas/delivery-dates' type: object carrier: type: object description: Carrier used for the shipment. readOnly: true properties: code: type: string title: Carrier Code description: A carrier represented by a Sendcloud unique identifier. example: postnl name: type: string title: Carrier Name description: Carrier friendly name. example: PostNL parcels-array-response: title: Parcels Array Response Object description: Parcel common object model type: object allOf: - $ref: '#/components/schemas/parcel-common' - type: object properties: created_at: type: string format: date-time description: The timestamp of when the parcel was created readOnly: true example: '2024-09-04T12:14:36.506925Z' updated_at: type: string format: date-time description: The timestamp of when the parcel was last updated readOnly: true example: '2024-09-04T12:14:47.203107Z' announced_at: type: - string - 'null' description: >- The timestamp of when the parcel was announced to the carrier (label was created) format: date-time readOnly: true example: '2024-09-04T12:14:47.153985Z' id: type: integer description: >- ID of the parcel (required to retrieve a parcel document for async announcement) readOnly: true status: $ref: '#/components/schemas/status' readOnly: true documents: type: array uniqueItems: true description: >- An array of documents. A parcel can contain multiple documents, for instance labels and a customs form. This field returns an array of all the available documents for this parcel. readOnly: true items: $ref: '#/components/schemas/documents' tracking_number: type: string description: Tracking number of the shipment. readOnly: true example: 3SYZXG8498635 tracking_url: type: - string - 'null' description: Tracking url of this shipment. readOnly: true additional_carrier_data: type: object title: Carrier-specific data readOnly: true description: Specific data that only belongs to some carriers. properties: awb_tracking_number: type: - string - 'null' description: >- Deutsche Post Global Mail only. This indicates the air waybill number of this box of Global Mail parcels. This will be set once the `Finalize box` has been called. box_number: type: - integer - 'null' description: >- Deutsche Post Global Mail only. This indicates the box to which this parcel belongs. This will be only set for Global Mail parcels. label_notes: type: - array - 'null' description: >- Custom messages printed on the shipping label. Use this field to include custom text - such as invoice numbers, product IDs, or internal reference codes - on the package’s shipping label. maxItems: 255 items: type: string example: The doorbell isn’t working minLength: 1 maxLength: 255 ErrorObject: title: Error type: object description: Error in a JSON:API error format properties: id: type: string description: A unique identifier for the error. links: type: object description: >- A set of hyperlinks that provide additional information about the error. properties: about: type: string description: A URL that provides additional information about the error. status: type: string format: int32 description: The HTTP status code of the error. minLength: 1 code: type: string description: A unique error code for the error, in snake case format. minLength: 1 enum: - unknown_field - invalid - forbidden - invalid_choice - min_value - 'null' - not_found - required - not_a_list - non_field_errors - authentication_failed - validation_error - parcel_announcement_error title: type: string description: A short, human-readable summary of the error. minLength: 1 detail: type: string description: A human-readable explanation of the error. minLength: 1 source: type: object description: >- An object that identifies the source of the error within the request payload. properties: pointer: type: string description: >- A `JSON` pointer to the location of the error within the request payload. parameter: type: string description: The name of the `query` parameter that caused the error. header: type: string description: The name of the `header` parameter that caused the error. meta: type: object description: Additional metadata about the error. shipment-common: title: Shipment common Object description: Shipment common object model type: object allOf: - $ref: '#/components/schemas/shipment-common-with-optional-fields' - type: object properties: customs_information: $ref: '#/components/schemas/customs-information' required: - ship_with address-with-sender-address-id: title: Sender Address ID type: object description: A sender address referenced by ID. properties: sender_address_id: description: >- The ID of a pre-configured sender address to ship from. A sender address can be added through the [Sendcloud platform](https://app.sendcloud.com/v2/settings/addresses/sender) and be retrieved using the [Retrieve a list of sender addresses](/api/v3/sender-addresses/retrieve-a-list-of-sender-addresses) endpoint. Note: if the sender address has a brand or tax numbers configured, those will be used by default. However, explicitly provided `brand_id` or `tax_numbers` in the request will always take precedence over the values from the sender address. example: 192 type: integer required: - sender_address_id address-with-required-fields: title: Address Object type: object description: Sendcloud Address object allOf: - $ref: '#/components/schemas/address' - required: - name - address_line_1 - postal_code - city - country_code service-point-request: title: Service Point description: >- Node for service point information. Use the [Retrieve a list of service points](/api/v2/service-points/retrieve-a-list-of-service-points) endpoint to find service points, or pass in the carrier's id for the service point. If both the `id` and `carrier_service_point_id` are provided, the `carrier_service_point_id` will be prioritised. type: object anyOf: - title: Sendcloud ID type: object properties: id: type: string description: The sendcloud `id` of a service point. example: '123' required: - id - title: Carrier Service Point ID type: object properties: carrier_service_point_id: type: string description: The carrier's id of a service point example: '123' required: - carrier_service_point_id label-details: title: Label details Object description: >- Describes the format and resolution of the label. **Note**: If you request a label in ZPL format and the carrier supports native ZPL, then it won't be possible to download the label in any other format later. type: object properties: mime_type: type: string default: application/pdf enum: - application/pdf - application/zpl - image/png example: application/zpl description: The format of the label dpi: type: integer description: >- The resolution of the label in **dots per inch**. ZPL labels are not affected by the DPI setting, as the resolution is determined by the carrier itself. Most carriers use a resolution of 203 DPI. Zebra printers need to be configured to print at the specific DPI of the label if they have higher resolution capabilities. default: 72 enum: - 72 - 203 - 300 - 600 example: 300 delivery-dates: title: Delivery Dates description: Defined delivery dates type: - object properties: handover_at: type: - string - 'null' format: date-time description: >- The date when the item will be handed over to the carrier by the merchant in ISO 8601 example: '2025-02-27T10:00:00.555309+00:00' deliver_at: type: - string - 'null' format: date-time description: The date when the order should reach the end customer in ISO 8601 example: '2025-03-15T10:00:00.555309+00:00' parcel-common: title: Parcel common Object description: Parcel common object model type: object allOf: - $ref: '#/components/schemas/parcel-common-with-optional-fields' - required: - weight - type: object properties: parcel_items: type: array description: >- List of items/products that the parcel contains. **Note that parcel items array is required for shipments that require customs documents.** maxItems: 1000 items: $ref: '#/components/schemas/parcel-item' service-point-response: title: Service Point description: Service point information returned in responses. type: object properties: id: type: string description: The `id` of a service point. example: '123' carrier_service_point_id: type: string description: The carrier's native id for the service point example: '91233' required: - id - carrier_service_point_id status: title: Status Object type: object description: Status object for a parcel properties: code: type: string example: ANNOUNCING message: type: string example: Being announced documents: title: Documents Object type: object description: Documents object for a parcel properties: type: type: string deprecated: true description: The type of the document. See the list below for available types. enum: - label - cn23 - cp71 - commercial-invoice - cn23-default - air-waybill - qr document_type: type: string description: The type of the document. See the list below for available types. enum: - label - customs-declaration - air-waybill size: type: string description: The paper size of the document. enum: - a6 - a4 link: type: string description: >- A link to the document, which allows downloading of the document in PDF, PNG and ZPL and various DPI. shipment-common-with-optional-fields: title: Shipment common with optional fields Object description: Shipment common with optional fields object model type: object properties: brand_id: description: > The `id` of the brand. Brands can be added through the [Sendcloud platform](https://app.sendcloud.com/v2/settings/brands/list) and be retrieved (alongside their `id`) from the [Retrieve a list of brands](/api/v2/brands/retrieve-a-list-of-brands) endpoint. example: 42 type: integer ship_with: $ref: '#/components/schemas/ship-with' to_address: $ref: '#/components/schemas/address-with-required-fields' order_number: type: string description: Order number generated manually or by shop system total_order_price: $ref: '#/components/schemas/optional-price' description: | The value paid by the buyer for the order. reference: description: > A reference that will be stored on the Shipment and returned in your responses. This is not sent to the carrier. type: - string - 'null' example: shipment-1234 external_reference_id: description: > An optional reference can be provided by the API user; if included, it must be unique across shipments of the user. Using the same reference more than once will result in a 409 HTTP status code and the associated object being returned. type: - string - 'null' example: unique-value-1234 validation_methods: type: array description: > A list of additional address validations to apply. At present, the only supported validation service is Here, and it is used exclusively for transactional contracts. To enable this feature, contract_id must be explicitly set and must reference a transactional contract. When using the "Here" validation method, Sendcloud will attempt to verify and correct the provided address based on the best available match from the selected provider. For example, if you submit "city": "Amstredan", the system will automatically correct it to "city": "Amsterdam". If no suitable match is found, the request will return an error. Please note that only address components recognised by the selected provider will be kept. Any additional details included in address fields (e.g. "address_line_2": "Ring the blue doorbell") will be removed if they do not match the provider records. For adding delivery notes or extra instructions, use the parcels.label_notes field instead. items: $ref: '#/components/schemas/address-validation-method-enum' example: - here required: - to_address customs-information: title: CustomsInformation type: object allOf: - $ref: '#/components/schemas/customs-information-with-optional-fields' - required: - invoice_number - export_reason address: title: Address Object type: object description: Sendcloud Address object properties: name: type: string example: John Doe description: Name of the person associated with the address minLength: 1 company_name: type: string example: Sendcloud description: Name of the company associated with the address address_line_1: type: string example: Stadhuisplein description: First line of the address house_number: type: string example: '50' description: House number of the address address_line_2: type: string description: Additional address information, e.g. 2nd level example: Apartment 17B postal_code: type: string example: 1013 AB description: Zip code of the address minLength: 1 city: type: string example: Eindhoven description: City of the address minLength: 1 po_box: type: - string - 'null' description: Code required in case of PO Box or post locker delivery state_province_code: type: string example: IT-RM description: >- The character state code of the customer represented as ISO 3166-2 code. This field is required for certain countries. See [international shipping](/docs/shipments/international-shipping#required-fields-for-international-shipments) for details. country_code: type: string example: NL description: The country code of the customer represented as ISO 3166-1 alpha-2 minLength: 1 email: type: string format: email example: johndoe@gmail.com description: Email address of the person associated with the address phone_number: type: string example: '+319881729999' description: Phone number of the person associated with the address parcel-common-with-optional-fields: title: Parcel common with optional fields Object description: Parcel common with optional fields model type: object properties: dimensions: $ref: '#/components/schemas/str-dimensions' description: >- While dimensions are optional, some carriers require them present. If this is the case, an error will be thrown. weight: $ref: '#/components/schemas/str-weight' additional_insured_price: $ref: '#/components/schemas/optional-price' description: >- Amount for which you want to add additional insurance (on top of carrier insurance) to the parcel with our insurance provider XCover. You can inure up from 2 euros to 5000 euros per shipment. label_notes: type: - array - 'null' description: >- Custom messages printed on the shipping label. Use this field to include custom text - such as invoice numbers, product IDs, or internal reference codes - on the package's shipping label. **Note that support for label messages varies by carrier; some carriers may ignore this field or offer alternatives, such as delivery instructions, which are communicated to the carrier but not printed on the label. Some carriers may apply label notes at the shipment level rather than per individual parcel.** maxItems: 255 items: type: string example: The doorbell isn’t working minLength: 1 maxLength: 255 sscc: type: - string - 'null' minLength: 18 maxLength: 18 pattern: ^\d{18}$ description: >- The Serial Shipping Container Code (SSCC) serves as a globally unique identifier for a logistic unit, functioning as a digital "license plate" for tracking and managing goods throughout the supply chain. example: '019844628346512933' package_type: type: - string - 'null' description: >- The package type defines how you pack your parcels. This field is mostly only required for carriers with specific needs, such as pallet carriers. For more information, reach out to your Sendcloud contact person. enum: - package - euro_pallet - block_pallet - mini_pallet - one_way_pallet - tube - over_size_pallet - bundle - half_pallet - letterbox - null example: package parcel-item: title: Parcel Item Object description: >- A single item in a shipment. **Note that parcel item object is required for shipments that require customs documents.** type: object allOf: - $ref: '#/components/schemas/parcel-item-with-optional-fields' - required: - hs_code - weight - description - price ship-with: title: Ship with object type: object description: > The ship with object can be used to define how you would like to send your shipment. You can use a `shipping_option_code`. This is a unique identifier that displays what carrier and what set of shipping functionalities you want to use. examples: - type: shipping_option_code properties: shipping_option_code: postnl:standard/insured=3000 contract_id: 517 properties: type: type: string description: > The way the shipping method and carrier will be selected. Nowadays the only possible value is 'shipping_option_code', which requires client to also send the `shipping_option_code` inside properties. enum: - shipping_option_code example: shipping_option_code properties: $ref: '#/components/schemas/shipping-option-code-properties' required: - type - properties optional-price: title: Optional price anyOf: - type: 'null' - $ref: '#/components/schemas/required-price' address-validation-method-enum: title: Address validation method enum type: string enum: - here customs-information-with-optional-fields: title: CustomsInformation with optional fields type: - object - 'null' description: >- Optional customs information that should be provided for international shipments. This information is used for generating customs documents. example: invoice_number: INV-123 export_reason: commercial_goods export_type: private invoice_date: '2023-08-24' discount_granted: value: '14.99' currency: EUR freight_costs: null insurance_costs: value: '3.60' currency: EUR other_costs: value: '1.2' currency: EUR goods_description: Electronic components and accessories general_notes: >- Compliance: Goods comply with international safety standards (CE certified). additional_declaration_statements: - >- With reference to the above shipment, I understate that the content is not made of leather parts of animal species protected by the Washington Convention. - >- I solemnly declare that the contents of this document represent a true and accurate account of the events as they occurred. I acknowledge my responsibility for the information presented herein and understand that any misrepresentation or falsification may result in legal consequences or other penalties as applicable. importer_of_record: name: John Doe company_name: ImporterCo address_line_1: Maple Avenue house_number: '123' postal_code: '90210' city: Springfield country_code: US state_province_code: US-MA telephone: '+15551234567' email: info@importer-of-record-example.com tax_numbers: sender: - name: VAT country_code: NL value: NL123456789B01 - name: EORI country_code: NL value: NL123456789 receiver: - name: EIN country_code: US value: '123456789' importer_of_record: - name: EIN country_code: US value: '987654321' properties: invoice_number: type: string minLength: 1 maxLength: 40 description: Customs invoice number. example: INV-123 export_reason: type: string description: >- Indicates the purpose or reason behind exporting the items. This classification helps customs authorities determine the applicable regulations, taxes, and duties. enum: - gift - documents - commercial_goods - commercial_sample example: commercial_goods export_type: type: string description: >- Export type documentation serves to categorize international shipments into three primary classifications: Private exports, intended for personal use; Commercial B2C exports, directed towards individual consumers; and Commercial B2B exports, involving business-to-business transactions. These distinctions facilitate adherence to regulatory requirements and ensure the orderly movement of goods across international boundaries. enum: - private - commercial_b2c - commercial_b2b default: commercial_b2c example: private invoice_date: type: string format: date description: >- The date when the commercial invoice for the goods was issued (ISO 8601). If not provided, the announcement date will be used by default. discount_granted: $ref: '#/components/schemas/optional-price' description: Shipper's granted discount amount to user. freight_costs: $ref: '#/components/schemas/optional-price' description: >- Charges associated with the transportation of the goods to their destination paid by the receiver. insurance_costs: $ref: '#/components/schemas/optional-price' description: >- The costs of insurance coverage for the goods during transit paid by the receiver. other_costs: $ref: '#/components/schemas/optional-price' description: >- Additional costs or charges associated with the shipment that are not covered by freight and insurance paid by the receiver. goods_description: type: string description: >- A description of the goods being shipped, used for customs clearance purposes. This field might not be supported by all carriers. maxLength: 255 example: Electronic components and accessories general_notes: type: string description: >- Exporter or shipper can include any additional information or special instructions related to the goods being shipped. This section is used to provide details that may not be covered in other parts of the invoice but are relevant for customs clearance. maxLength: 500 example: >- Compliance: Goods comply with international safety standards (CE certified). additional_declaration_statements: type: array description: >- List of additional declaration statements. Each statement may contain specific details about the nature of the goods being shipped, their origin, or any additional information required by customs authorities. The content of an additional declaration statement can vary based on the requirements of the importing and exporting countries, as well as the nature of the goods being transported. maxItems: 100 items: type: string example: >- With reference to the above shipment, I understate that the content is not made of leather parts of animal species protected by the Washington Convention. minLength: 1 maxLength: 1024 importer_of_record: type: - object - 'null' description: >- Importer of Record (IOR) information. A customs-connected record importer specializes in importing goods and managing the associated customs documentation. If not provided, the receiver's address will be used instead. properties: name: type: string description: Name of IOR minLength: 1 maxLength: 75 company_name: type: string description: IOR company name maxLength: 50 address_line_1: type: string description: Address of IOR minLength: 1 maxLength: 150 address_line_2: type: string description: Additional address information, e.g. 2nd level maxLength: 150 house_number: type: string description: IOR house number maxLength: 20 city: type: string description: IOR city minLength: 1 maxLength: 30 postal_code: type: string description: IOR postal code minLength: 1 maxLength: 12 country_code: type: string description: IOR country. ISO 3166-1 alpha-2 code minLength: 2 maxLength: 2 state_province_code: type: string description: >- Code of the state (e.g. NY for New York) or province (e.g. RM for Rome). Destinations that require this field are USA, Canada, Italy and Australia. Format ISO-3166-2. See [international shipping](/docs/shipments/international-shipping#required-fields-for-international-shipments) for details. example: IT-RM maxLength: 14 telephone: type: string description: IOR phone number in E.164 format maxLength: 20 email: type: string description: IOR email maxLength: 320 required: - name - address_line_1 - city - postal_code - country_code tax_numbers: type: object description: >- Identification numbers and codes related to sender, received and importer of record provider. properties: sender: type: array description: Sender's list of identification number objects maxItems: 20 items: $ref: '#/components/schemas/TaxNumber' receiver: type: array description: Receiver's list of identification number objects maxItems: 20 items: $ref: '#/components/schemas/TaxNumber' importer_of_record: type: array description: Importer of record's list of identification number objects items: $ref: '#/components/schemas/TaxNumber' maxItems: 20 required: - sender - receiver - importer_of_record required: - invoice_number str-dimensions: title: Dimensions type: object description: Dimensions in the specified unit properties: length: type: string description: length in specified unit example: '15' width: type: string description: width in specified unit example: '20.5' height: type: string description: height in specified unit example: '37' unit: $ref: '#/components/schemas/dimension-units' required: - length - width - height - unit str-weight: title: Weight type: object description: Weight in the specified unit properties: value: type: string description: Weight value example: '14.5' unit: $ref: '#/components/schemas/weight-units' required: - value - unit parcel-item-with-optional-fields: title: Parcel Item with optional fields Object description: >- A single item (with optional fields) in a shipment. **Note that parcel item object is required for shipments that require customs documents.** type: object properties: item_id: type: string description: Order Item external ID in shop system example: '5552' minLength: 1 description: type: string description: Description of the item example: T-Shirt XL minLength: 1 maxLength: 255 quantity: type: integer description: Quantity of items shipped minimum: 1 example: 1 weight: $ref: '#/components/schemas/weight' price: $ref: '#/components/schemas/required-price' hs_code: type: string description: >- Harmonized System Code. **This field is required if it's an international shipment** example: '620520' maxLength: 12 origin_country: type: string description: >- ISO-2 code of the country where the items were originally produced. **This field is required if it's an international shipment** example: NL sku: type: string description: The SKU of the product example: TS1234 product_id: type: string description: The internal ID of the product example: '19284' mid_code: title: MID Code type: - string - 'null' description: >- MID code is short for Manufacturer's Identification code and must be shown on the commercial invoice. It's used as an alternative to the full name and address of a manufacturer, shipper or exporter and is always required for U.S. formal customs entries. example: NLOZR92MEL material_content: title: Material Content type: - string - 'null' description: A description of materials of the order content. example: 100% Cotton intended_use: title: Intended Use type: - string - 'null' description: >- Intended use of the order contents. The intended use may be personal or commercial. example: Personal use dangerous_goods: $ref: '#/components/schemas/dangerous-goods' dds_reference: title: DDS Reference type: - string - 'null' description: >- The DDS (Due Diligence Statement) reference number associated with the item, if applicable. See EUDR system for more details. example: 25FIYPEK0A7573 taric_doc_code: title: TARIC document code type: - string - 'null' description: >- TARIC document codes are specific alphanumeric codes used in EU customs declarations (Box 44) to identify required supporting documents, certificates, or conditions for a product, like health certificates (e.g., 3200), origin proofs (e.g., EUR.1), or special authorizations (e.g., C716 for due diligence) for simplified procedures, ensuring compliance with EU trade rules for various goods. example: Y142 properties: type: object additionalProperties: true description: Any custom user-defined properties of order item or product example: size: red color: green required: - quantity shipping-option-code-properties: title: Shipping option properties Object description: >- Contains the required properties to be sent when API client informs the shipping method and carrier to be used type: object properties: shipping_option_code: type: - string - 'null' description: >- The shipping option that will be or is used for shipping your parcel. The code can be retrieved via the [Create a list of shipping options](/api/v3/shipping-options/create-a-list-of-shipping-options) endpoint. When `ship_with.type` is set to `shipping_option_code`, this field is mandatory. example: postnl:standard/insured=3000 contract_id: type: - integer - 'null' minimum: 1 description: >- The selected shipping contract. If you haven't specified a contract for shipping your parcel, we will automatically select the default contract for the carrier that matches your shipping option. You can retrieve your contract IDs from the [Retrieve a list of contracts](/api/v3/contracts/retrieve-a-list-of-contracts) endpoint. Otherwise, the default direct contract will be automatically selected. required-price: title: Price object description: Price, consisting of a value and currency. allOf: - $ref: '#/components/schemas/Price' - type: object required: - value - currency TaxNumber: title: Tax Number Object description: >- Identification numbers and codes used in different contexts. These identifiers are used for taxation, customs, business registration, and other purposes, depending on the country and the specific regulatory requirements. Depending on these requirements you may need to pass one or several numbers related to sender, receiver or importer of record provider. These numbers and codes will be included into final Customs documents. type: object properties: name: type: string example: EORI description: | Tax number abbreviation * VAT - Value-Added Tax → VOEC number for Norway should be shared here as advised by the [Norwegian Tax Authorities](https://www.skatteetaten.no/globalassets/bedrift-og-organisasjon/voec/sending-and-marking-goods-through-postal-services-and-transporters.pdf) * EIN - Employer Identification Number * GST - Goods and Service Tax * SSN - Social Security Number * EORI - Economic Operators Registration and Identification for the European Union * DUN - Data Universal Numbering System * FED - Federal Tax ID * STA - State Tax ID * CNP - Brazil CNPJ/CPF Federal Tax * IE - Brazil type IE/RG Federal Tax * INN - Russia bank details section INN * KPP - Russia bank details section KPP * OGR - Russia bank details section OGRN * OKP - Russia bank details section OKPO * IOSS - SDT or Overseas Registered Supplier or Import One-Stop-Shop or GB VAT (foreign) registration or AUSid GST Registration or VAT on E-Commerce * FTZ - Free Trade Zone ID * DAN - Deferment Account Duties Only * TAN - Deferment Account Tax Only * DTF - Deferment Account Duties, Taxes and Fees Only * RGP - EU Registered Exporters Registration ID * DLI - Driver's License * NID - National Identity Card - A PID (Personal Identification Number) should be provided as NID (National Identity Card). * PAS - Passport * MID - Manufacturer ID * UKIMS - UK Internal Market Scheme -> customs clearance for shipping from Great Britain to Northern Ireland under the Windsor Framework, for more information see [Windsor Framework](https://www.gov.uk/government/publications/the-windsor-framework) enum: - VAT - EIN - GST - SSN - EORI - DUN - FED - STA - CNP - IE - INN - KPP - OGR - OKP - IOSS - FTZ - DAN - TAN - DTF - RGP - DLI - NID - PAS - MID - UKIMS country_code: type: string example: NL description: Issuing country code (ISO 3166-1 alpha-2 code) maxLength: 2 value: type: string example: NL123456789B01 description: Tax number itself maxLength: 100 required: - name - country_code - value dimension-units: type: string title: Dimensional units enum: - cm - mm - m - yd - ft - in example: mm weight-units: type: string title: Mass Units Object enum: - kg - g - lbs - oz example: g weight: title: Weight type: object description: Weight in the specified unit properties: value: type: number description: Weight value exclusiveMinimum: 0 example: 14.5 unit: $ref: '#/components/schemas/weight-units' required: - value - unit dangerous-goods: title: DangerousGoods type: object description: Hazardous materials information for items. properties: chemical_record_identifier: type: string nullable: true description: Chemical record identifier for the dangerous goods regulation_set: type: string enum: - IATA - ADR description: Regulation set governing the dangerous goods packaging_type_quantity: type: string nullable: true description: Quantity of packaging type packaging_type: type: string nullable: true description: Type of packaging used packaging_instruction_code: type: string nullable: true description: Packaging instruction code id_number: type: string nullable: true description: UN identification number class_division_number: type: string nullable: true description: Hazard class and division number quantity: type: string nullable: true description: Quantity of dangerous goods unit_of_measurement: type: string enum: - KG - G - L - ML description: Unit of measurement for dangerous goods quantity proper_shipping_name: type: string nullable: true description: Proper shipping name as defined by regulations commodity_regulated_level_code: type: string enum: - LQ - EQ description: Commodity regulated level code transportation_mode: type: string enum: - Highway - Ground - PAX - CAO description: Mode of transportation emergency_contact_name: type: string nullable: true description: Name of emergency contact person emergency_contact_phone: type: string nullable: true description: Phone number of emergency contact adr_packing_group_letter: type: string enum: - I - II - III description: ADR packing group classification local_proper_shipping_name: type: string nullable: true description: Local proper shipping name transport_category: type: string nullable: true description: Transport category for ADR regulations tunnel_restriction_code: type: string nullable: true description: Tunnel restriction code weight_type: type: string enum: - Net - Gross description: Type of weight measurement Price: title: Price Object type: object properties: value: type: string example: '12.65' pattern: '[\d]+(\.[\d]+)?' currency: type: string description: ISO 4217 currency code minLength: 3 maxLength: 3 example: USD securitySchemes: HTTPBasicAuth: type: http description: >- Basic Authentication using API key and secrets is currently the main authentication mechanism. scheme: basic OAuth2ClientCreds: type: oauth2 description: >- OAuth2 is a standardized protocol for authorization that allows users to share their private resources stored on one site with another site without having to provide their credentials. OAuth2 Client Credentials Grant workflow. This workflow is typically used for server-to-server interactions that require authorization to access specific resources. flows: clientCredentials: tokenUrl: https://account.sendcloud.com/oauth2/token/ scopes: api: Default OAuth scope required to access Sendcloud API. ````