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 tags: - name: Shipments description: Shipments API paths: /shipments/announce: post: summary: Create and announce a shipment synchronously description: This endpoint **announces a shipment synchronously** under your API credentials. x-mint: href: /api/v3/shipments/create-and-announce-a-shipment-synchronously content: |- ## 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. tags: - Shipments operationId: sc-public-v3-scp-post-announce_shipment parameters: - $ref: '#/components/parameters/SendcloudPartnerId' requestBody: content: application/json: schema: $ref: '#/components/schemas/shipment-request-sync-announce' examples: CreateDomesticSingleParcelShipment: summary: Create a domestic shipment (with a single parcel) value: label_details: mime_type: application/pdf dpi: 72 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 label_notes: - I live at the blue door - The doorbell isn't working 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 manufacturer_product_id: ABC-12345 manufacturer_product_id_std: '01234567890128' 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: label_details: mime_type: application/pdf dpi: 72 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 manufacturer_product_id: XYZ-98765 manufacturer_product_id_std: null 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' description: '' responses: '201': description: Shipment response content: application/json: schema: description: Create a shipment type: object title: Announced shipment including label properties: data: $ref: '#/components/schemas/sync-shipment-response' examples: CreatedSingleParcelDomesticShipment: summary: Domestic Shipment (with single parcel) created value: data: id: XXX-Shipment-id label_details: mime_type: application/pdf dpi: 72 order_number: '1234567890' total_order_price: currency: EUR value: '11.11' parcels: - id: 383707309 status: code: READY_TO_SEND message: Ready to send documents: - type: label size: a6 link: https://panel.sendcloud.sc/api/v3/parcels/383707309/documents/label dimensions: width: '15.00' length: '5.00' height: '20.00' unit: cm weight: value: '1.320' unit: kg tracking_url: https://tracking.eu-central-1-0.sendcloud.sc/forward?carrier=postnl&code=3SYZXG8498635&destination=NL&lang=en-us&source=NL&type=parcel&verification=5642+CV&servicepoint_verification=&created_at=2024-06-06 tracking_number: 3SYZXG8498635 tracking_numbers: - tracking_number: 3SYZXG8498635 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: '2024-06-06T17:11:14.712398Z' label_notes: - I live at the blue door - The doorbell isn't working package_type: package 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 manufacturer_product_id: null manufacturer_product_id_std: '09876543210987' 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 483 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 label_details: mime_type: application/pdf dpi: 72 order_number: '1234567890' total_order_price: currency: EUR value: '11.11' parcels: - id: 383707309 status: code: READY_TO_SEND message: Ready to send documents: - type: label size: a6 link: https://panel.sendcloud.sc/api/v3/parcels/383707309/documents/label dimensions: width: '15.00' length: '5.00' height: '20.00' unit: cm weight: value: '1.320' unit: kg tracking_url: https://tracking.eu-central-1-0.sendcloud.sc/forward?carrier=postnl&code=3SYZXG8498635&destination=NL&lang=en-us&source=NL&type=parcel&verification=5642+CV&servicepoint_verification=&created_at=2024-06-06 tracking_number: 3SYZXG8498635 tracking_numbers: - tracking_number: 3SYZXG8498635 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: '2024-06-06T17:11:14.712398Z' 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 manufacturer_product_id: ABC-12345 manufacturer_product_id_std: '01234567890128' 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: [] DomesticSingleParcelShipmentAnnouncementFailed: summary: Domestic with a single parcel shipment created, but announcement failed value: data: id: XXX-Shipment-id order_number: '1234567890' total_order_price: currency: EUR value: '11.11' parcels: - id: 383707309 created_at: '2018-01-01T21:45:30' updated_at: '2018-01-01T21:47:12' announced_at: '2018-01-01T21:47:13' tracking_number: 3SYZXG8498635 tracking_numbers: - tracking_number: 3SYZXG8498635 dimensions: length: '5.00' width: '15.00' height: '20.00' unit: cm weight: value: '1.320' unit: kg status: code: ANNOUNCEMENT_FAILED message: Announcement Failed additional_carrier_data: awb_tracking_number: null box_number: 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: null 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 manufacturer_product_id: XYZ-98765 manufacturer_product_id_std: null properties: size: 42 color: black to_address: name: John Doe company_name: Sendcloud address_line_1: Insulindelaan 115 address_line_2: '' house_number: '115' postal_code: 5642CV city: Eindhoven country_code: NL phone_number: '+31612345678' email: john.doe@sendcloud.com state_province_code: '' 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: 5A postal_code: 5611 EM city: Eindhoven country_code: NL phone_number: '+31612345678' email: marie.doe@sendcloud.com state_province_code: '' po_box: PO Box 483 ship_with: type: shipping_option_code properties: shipping_option_code: postnl:standard contract_id: 517 carrier: code: postnl name: PostNL errors: - status: '500' code: parcel_announcement_error detail: 'Service error: An error occurred while connecting to the carrier.' '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: /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 '409': description: Conflict — a shipment with this external_reference_id already exists; the existing shipment is returned. content: application/json: schema: $ref: '#/components/schemas/sync-shipment-response' security: - HTTPBasicAuth: [] - OAuth2ClientCreds: [] /shipments: get: summary: Retrieve shipments description: |- This endpoint allows you to retrieve a list of all the shipments which you have created or imported into your Sendcloud account under your API credentials. You can filter the results based on several query parameters. This endpoint uses cursor-based pagination via `Link` headers. See [Pagination](/api/v3/pagination) for details. x-mint: href: /api/v3/shipments/retrieve-shipments x-sendcloud-paginated: true x-sendcloud-paginated-discriminator: shipments tags: - Shipments responses: '200': description: OK content: application/json: schema: description: Retrieve shipments type: object properties: data: type: array uniqueItems: true minItems: 1 items: $ref: '#/components/schemas/shipment-response' required: - data examples: RetrievedDomesticSingleParcelShipments: summary: Retrieve shipments with a single parcel) value: data: - id: XXX-Shipment-id order_number: '1234567890' total_order_price: currency: EUR value: '11.11' parcels: - id: 383707309 status: code: CANCELLED message: Cancelled documents: - type: label size: a6 link: https://panel.sendcloud.sc/api/v3/parcels/383707309/documents/label dimensions: width: '15.00' length: '5.00' height: '20.00' unit: cm weight: value: '1.320' unit: kg tracking_url: https://tracking.eu-central-1-0.sendcloud.sc/forward?carrier=postnl&code=3SYZXG5051720&destination=NL&lang=en-us&source=NL&type=parcel&verification=5642+CV&servicepoint_verification=&created_at=2024-06-07 tracking_number: 3SYZXG5051720 tracking_numbers: - tracking_number: 3SYZXG5051720 additional_carrier_data: awb_tracking_number: null box_number: null created_at: '2024-06-07T09:02:18.864105Z' updated_at: '2024-06-07T09:32:22.804278Z' announced_at: '2024-06-07T09:02:19.480225Z' label_notes: - I live at the blue door - The doorbell isn’t working package_type: package 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 manufacturer_product_id: null manufacturer_product_id_std: '09876543210987' 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 483 ship_with: type: shipping_option_code properties: shipping_option_code: postnl:standard contract_id: 517 customs_information: null headers: Link: description: The pagination links, according to the web linking specification (RFC8288). schema: type: string example: ; rel="prev", ; rel="next" '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/errors' examples: ValidationError: summary: Datetime parsing error value: errors: - detail: Validation failed, announced_after is not a datetime status: '404' source: pointer: /list_shipments/filters code: validation_error '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/errors' examples: InvalidCursor: summary: Invalid cursor value: errors: - detail: Invalid cursor status: '404' source: pointer: /data code: not_found operationId: sc-public-v3-scp-get-all_shipments security: - HTTPBasicAuth: [] - OAuth2ClientCreds: [] parameters: - schema: oneOf: - type: string - type: integer in: query name: parcel_status description: Returns shipments that have the requested status. For a list of possible statuses, see the [Retrieve a list of parcel statuses](/api/v3/parcel-statuses/retrieve-a-list-of-parcel-statuses) endpoint. - schema: type: string in: query name: tracking_number description: Returns shipments that match a specified tracking number - schema: type: string in: query name: external_reference_id description: Returns shipments that match a specified external reference - schema: type: string in: query name: order_number description: Returns a shipment that matches a specific `order_number` property from your shipments - schema: type: string in: query name: integration_id description: Returns all shipments that matches a specific `integration_id` property from your shipments - schema: type: string example: '2018-02-26T11:01:47.505309+00:00' in: query name: updated_before description: Returns all shipments which have been updated in our system before a given time. Use the ISO 8601 datetime format. - schema: type: string example: '2018-02-26T11:01:47.505309+00:00' in: query name: updated_after description: Returns all shipments which have been updated in our system after a given time. Use the ISO 8601 datetime format. - schema: type: string example: '2018-02-26T11:01:47.505309+00:00' in: query name: announced_before description: Returns all shipments which have been announced to the carrier before the given time. Use the ISO 8601 datetime format. - schema: type: string example: '2018-02-26T11:01:47.505309+00:00' in: query name: announced_after description: Returns all shipments which have been announced to the carrier after the given time. Use the ISO 8601 datetime format. - schema: type: string example: 13579,24680,12345 in: query name: ids description: Filter results using a comma-separated list of *parcels IDs*. The list may not contain more than 100 IDs. - schema: type: string example: 4df31240-daef-40bf-81fc-7a83184073e6,adbb3dce-9756-42b0-838d-a478a5236289 in: query name: shipment_uuids description: Filter results using a comma-separated list of *shipments IDs*. The list may not contain more than 100 IDs. - $ref: '#/components/parameters/Cursor' - schema: type: integer minimum: 1 default: 40 maximum: 100 example: 10 in: query name: page_size description: The maximum number of items to be returned in the response. post: summary: Create and announce a shipment asynchronously description: This endpoint **announces a shipment asynchronously** under your API credentials. x-mint: href: /api/v3/shipments/create-and-announce-a-shipment-asynchronously content: |- ## 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). tags: - Shipments operationId: sc-public-v3-scp-post-create_shipment security: - HTTPBasicAuth: [] - OAuth2ClientCreds: [] 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: '' tracking_numbers: [] 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 manufacturer_product_id: ABC-12345 manufacturer_product_id_std: '01234567890128' 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: '' tracking_numbers: [] 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 manufacturer_product_id: XYZ-98765 manufacturer_product_id_std: null 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_numbers: [] 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_numbers: [] 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 '409': description: Conflict — a shipment with this external_reference_id already exists; the existing shipment is returned. content: application/json: schema: $ref: '#/components/schemas/shipment-response' 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 manufacturer_product_id: null manufacturer_product_id_std: '09876543210987' 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 manufacturer_product_id: ABC-12345 manufacturer_product_id_std: '01234567890128' 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 manufacturer_product_id: XYZ-98765 manufacturer_product_id_std: null 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: '' /shipments/announce-with-shipping-rules: post: summary: Create a shipment with rules and/or defaults and announce it synchronously description: Create and announce a shipment applying shipping rules and/or defaults x-mint: href: /api/v3/shipments/create-a-shipment-with-rules-and-or-default-and-announce-it-synchronously content: |- The main advantage of this endpoint over the [Create and announce a shipment synchronously](/api/v3/shipments/create-and-announce-a-shipment-synchronously) endpoint (and also the difference between them) is the ability to apply [shipping rules](https://app.sendcloud.com/v2/shipping/rules) and [shipping defaults](https://app.sendcloud.com/v2/shipping/shipping-defaults) to a shipment. Because of this, more fields in this endpoint are optional. If no shipping rules or defaults are configured to automatically assign the fields listed below, those fields must be provided to create a shipment successfully: - `from_address` (from Ship with address) - `ship_with` (from Ship with) - `parcels` (from Set number of parcels) **Note: the shipment (parcels) will be linked to the integration identified by the API credentials you supply as request authentication (`Basic ...`).** ## Shipping rules - **Due to the data (shipments) that we receive in this API, NOT all of the shipping rules (actions or conditions) can (and will) be applied.** - **Shipping rules do not fully apply to multicollo shipments. In such cases, the rule conditions for weight, parcel dimensions (height, length, width), total order value, item name, item quantity, item SKU and total parcel item value will not be matched. Additionally, the following actions will not be triggered:** - Using a box (Use box) - Setting the weight (Set weight) - Setting the number of parcels (Set number of parcels) - Insuring the shipment value (Insure shipment value by) - Insuring it by percentage (Insure shipment value by %) - Increasing item value by percentage (Decrease item value by %) - Setting item HS code (Set Item HS Code) - Setting item name (Set item name) - Setting item origin country (Set Item Origin Country) - Setting item value (Set item value) - Setting item weight (Set item weight) **Please consider these limitations when defining rules.** ### Shipping rules conditions (IF) that can be applied - Carrier - Checkout delivery method - Company name - Customer email - Integration - Item SKU - Item name - Item quantity - Parcel height (cm) - Parcel length (cm) - Parcel width (cm) - Phone number - Postal code - To country - Total order value - Total parcel item value - Weight (kg) ## Shipping rules actions (THEN) that can be applied - Add customs declaration statement - Use box - Decrease item value by % - Insure shipment value by - Insure shipment value by % - Set customs general notes - Set customer email - Set Item HS Code - Set item name - Set Item Origin Country - Set item value - Set item weight - Set number of parcels - Phone number - Ship with address - Ship with - Set weight - Use shipping contract tags: - Shipments operationId: sc-public-v3-scp-post-announce_shipment_with_rules security: - HTTPBasicAuth: [] - OAuth2ClientCreds: [] responses: '201': description: Shipment response content: application/json: schema: description: Create a shipment type: object title: Announced shipment including label properties: data: $ref: '#/components/schemas/sync-shipment-with-rules-response' examples: CreatedSingleParcelDomesticShipment: summary: Domestic Shipment (with single parcel) created value: data: id: XXX-Shipment-id label_details: mime_type: application/pdf dpi: 72 order_number: '1234567890' total_order_price: currency: EUR value: '11.11' parcels: - id: 383707309 status: code: READY_TO_SEND message: Ready to send documents: - type: label size: a6 link: https://panel.sendcloud.sc/api/v3/parcels/383707309/documents/label dimensions: width: '15.00' length: '5.00' height: '20.00' unit: cm weight: value: '1.320' unit: kg tracking_url: https://tracking.eu-central-1-0.sendcloud.sc/forward?carrier=postnl&code=3SYZXG8498635&destination=NL&lang=en-us&source=NL&type=parcel&verification=5642+CV&servicepoint_verification=&created_at=2024-06-06 tracking_number: 3SYZXG8498635 tracking_numbers: - tracking_number: 3SYZXG8498635 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: '2024-06-06T17:11:14.712398Z' label_notes: - I live at the blue door - The doorbell isn't working package_type: package 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 manufacturer_product_id: null manufacturer_product_id_std: '09876543210987' 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 483 ship_with: type: shipping_option_code properties: shipping_option_code: postnl:standard contract_id: 517 customs_information: null carrier: code: postnl name: PostNL errors: [] applied_shipping_rules: - rule: id: 315157 name: Ship with PostNL for NL result: shipping_option_code: postnl:standard CreatedCustomsRequiredShipment: summary: Shipment (with Customs and a single parcel) created value: data: id: XXX-Shipment-id label_details: mime_type: application/pdf dpi: 72 order_number: '1234567890' total_order_price: currency: EUR value: '11.11' parcels: - id: 383707309 status: code: READY_TO_SEND message: Ready to send documents: - type: label size: a6 link: https://panel.sendcloud.sc/api/v3/parcels/383707309/documents/label dimensions: width: '15.00' length: '5.00' height: '20.00' unit: cm weight: value: '1.320' unit: kg tracking_url: https://tracking.eu-central-1-0.sendcloud.sc/forward?carrier=postnl&code=3SYZXG8498635&destination=NL&lang=en-us&source=NL&type=parcel&verification=5642+CV&servicepoint_verification=&created_at=2024-06-06 tracking_number: 3SYZXG8498635 tracking_numbers: - tracking_number: 3SYZXG8498635 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: '2024-06-06T17:11:14.712398Z' 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 manufacturer_product_id: ABC-12345 manufacturer_product_id_std: '01234567890128' 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: [] applied_shipping_rules: - rule: id: 315157 name: Ship with DHL Express for GB result: shipping_option_code: dhl_express:worldwide/incoterm=dap DomesticSingleParcelShipmentAnnouncementFailed: summary: Domestic with a single parcel shipment created, but announcement failed value: data: id: XXX-Shipment-id order_number: '1234567890' total_order_price: currency: EUR value: '11.11' parcels: - id: 383707309 created_at: '2018-01-01T21:45:30' updated_at: '2018-01-01T21:47:12' announced_at: '2018-01-01T21:47:13' tracking_number: 3SYZXG8498635 tracking_numbers: - tracking_number: 3SYZXG8498635 dimensions: length: '5.00' width: '15.00' height: '20.00' unit: cm weight: value: '1.320' unit: kg status: code: ANNOUNCEMENT_FAILED message: Announcement Failed additional_carrier_data: awb_tracking_number: null box_number: 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 to_address: name: John Doe company_name: Sendcloud address_line_1: Insulindelaan 115 address_line_2: '' house_number: '115' postal_code: 5642CV city: Eindhoven country_code: NL phone_number: '+31612345678' email: john.doe@sendcloud.com state_province_code: '' 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: 5A postal_code: 5611 EM city: Eindhoven country_code: NL phone_number: '+31612345678' email: marie.doe@sendcloud.com state_province_code: '' po_box: PO Box 483 ship_with: type: shipping_option_code properties: shipping_option_code: postnl:standard contract_id: 517 carrier: code: postnl name: PostNL errors: - status: '500' code: parcel_announcement_error detail: 'Service error: An error occurred while connecting to the carrier.' applied_shipping_rules: - rule: id: 315157 name: Ship with PostNL for NL result: shipping_option_code: postnl:standard '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: /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 '409': description: Conflict — a shipment with this external_reference_id already exists; the existing shipment is returned. content: application/json: schema: $ref: '#/components/schemas/sync-shipment-with-rules-response' parameters: - $ref: '#/components/parameters/SendcloudPartnerId' requestBody: content: application/json: schema: $ref: '#/components/schemas/shipment-request-with-rules' examples: CreateShipmentWithRulesAndDefaultsAndDeliveryIndicator: summary: Create a shipment with defaults and rules (using delivery_indicator) value: apply_shipping_defaults: true apply_shipping_rules: true delivery_indicator: DHL home delivery 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 manufacturer_product_id: XYZ-98765 manufacturer_product_id_std: null 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 CreateShipmentWithOnlyRules: summary: Create a shipment with only rules (not defaults) value: apply_shipping_defaults: false apply_shipping_rules: true 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 CreateShipmentWithOnlyDefaults: summary: Create a shipment with only defaults (not rules) value: apply_shipping_defaults: true apply_shipping_rules: false 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 manufacturer_product_id: null manufacturer_product_id_std: '09876543210987' 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 CreateShipmentWithoutRulesAndDefaults: summary: Create a shipment without rules and defaults value: apply_shipping_defaults: false apply_shipping_rules: false 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 description: '' /shipments/create-with-shipping-rules: post: summary: Create a shipment with rules and/or defaults and announce it asynchronously description: Create and announce a shipment applying shipping rules and/or defaults asynchronously. x-mint: href: /api/v3/shipments/create-a-shipment-with-rules-and-or-default-and-announce-it-asynchronously content: |- The main advantage of this endpoint over the [Create and announce a shipment asynchronously](/api/v3/shipments/create-and-announce-a-shipment-asynchronously) endpoint (and also the difference between them) is the ability to apply [shipping rules](https://app.sendcloud.com/v2/shipping/rules) and [shipping defaults](https://app.sendcloud.com/v2/shipping/shipping-defaults) to a shipment. Because of this, more fields in this endpoint are optional. If no shipping rules or defaults are configured to automatically assign the fields listed below, those fields must be provided to create a shipment successfully: - `from_address` (from Ship with address) - `ship_with` (from Ship with) - `parcels` (from Set number of parcels) **Note: the shipment (parcels) will be linked to the integration identified by the API credentials you supply as request authentication (`Basic ...`).** ## Shipping rules - **Due to the data (shipments) that we receive in this API, NOT all of the shipping rules (actions or conditions) can (and will) be applied.** - **Shipping rules do not fully apply to multicollo shipments. In such cases, the rule conditions for weight, parcel dimensions (height, length, width), total order value, item name, item quantity, item SKU and total parcel item value will not be matched. Additionally, the following actions will not be triggered:** - Using a box (Use box) - Setting the weight (Set weight) - Setting the number of parcels (Set number of parcels) - Insuring the shipment value (Insure shipment value by) - Insuring it by percentage (Insure shipment value by %) - Increasing item value by percentage (Decrease item value by %) - Setting item HS code (Set Item HS Code) - Setting item name (Set item name) - Setting item origin country (Set Item Origin Country) - Setting item value (Set item value) - Setting item weight (Set item weight) **Please consider these limitations when defining rules.** ### Shipping rules conditions (IF) that can be applied - Carrier - Checkout delivery method - Company name - Customer email - Integration - Item SKU - Item name - Item quantity - Parcel height (cm) - Parcel length (cm) - Parcel width (cm) - Phone number - Postal code - To country - Total order value - Total parcel item value - Weight (kg) ## Shipping rules actions (THEN) that can be applied - Add customs declaration statement - Use box - Decrease item value by % - Insure shipment value by - Insure shipment value by % - Set customs general notes - Set customer email - Set Item HS Code - Set item name - Set Item Origin Country - Set item value - Set item weight - Set number of parcels - Phone number - Ship with address - Ship with - Set weight - Use shipping contract tags: - Shipments operationId: sc-public-v3-scp-post-create_shipment_with_rules security: - HTTPBasicAuth: [] - OAuth2ClientCreds: [] responses: '201': description: OK content: application/json: schema: description: Create a shipment type: object title: Shipment created response properties: data: $ref: '#/components/schemas/shipment-with-rules-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: '' tracking_numbers: [] 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 manufacturer_product_id: ABC-12345 manufacturer_product_id_std: '01234567890128' 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: [] applied_shipping_rules: - rule: id: 315157 name: Ship with PostNL for NL result: shipping_option_code: postnl:standard 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: '' tracking_numbers: [] 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: [] applied_shipping_rules: - rule: id: 315157 name: Ship with DHL Express for GB result: shipping_option_code: dhl_express:worldwide/incoterm=dap 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.300' 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_numbers: [] 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_numbers: [] 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: 1 carrier: code: postnl name: PostNL errors: [] applied_shipping_rules: - rule: id: 315157 name: Ship with PostNL for NL result: shipping_option_code: postnl:standard '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 '409': description: Conflict — a shipment with this external_reference_id already exists; the existing shipment is returned. content: application/json: schema: $ref: '#/components/schemas/shipment-with-rules-response' parameters: - $ref: '#/components/parameters/SendcloudPartnerId' requestBody: content: application/json: schema: $ref: '#/components/schemas/shipment-request-with-rules' examples: CreateShipmentWithRulesAndDefaultsAndDeliveryIndicator: summary: Create a shipment with defaults and rules (using delivery_indicator) value: apply_shipping_defaults: true apply_shipping_rules: true delivery_indicator: DHL home delivery 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 manufacturer_product_id: XYZ-98765 manufacturer_product_id_std: null 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 CreateShipmentWithOnlyRules: summary: Create a shipment with only rules (not defaults) value: apply_shipping_defaults: false apply_shipping_rules: true 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 CreateShipmentWithOnlyDefaults: summary: Create a shipment with only defaults (not rules) value: apply_shipping_defaults: true apply_shipping_rules: false 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 manufacturer_product_id: null manufacturer_product_id_std: '09876543210987' properties: size: 42 color: black CreateShipmentWithoutRulesAndDefaults: summary: Create a shipment without rules and defaults value: apply_shipping_defaults: false apply_shipping_rules: false 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 description: '' /addresses/validate: post: summary: Validate an address tags: - Address - Returns - Shipments operationId: sc-public-v3-scp-post-validate_address security: - HTTPBasicAuth: [] description: |- This address validation endpoint allows you to validate shipping addresses before using them. By validating addresses in advance, you can ensure that the shipping information is accurate and complete, reducing the risk of delivery issues and improving overall shipping efficiency. Providing the carrier helps to tailor the address validation process according to specific carrier requirements. Using additional validation methods can further enhance the accuracy of the address verification. The default Sendcloud validation, will always be applied, has in 2 steps: 1. checks the address against the carrier limits (e.g. maximum length of the address line, existence of the postal code for the country, etc.). see also [Carrier address limits](/docs/addresses/address-field-limits#address-field-limits). 2. optimizes (washes) the address to fit within the carrier limits. (e.g. deduplication of address lines, abbreviations, etc.) x-mint: href: /api/v3/address/validate content: |- This address validation endpoint allows you to validate shipping addresses before using them. By validating addresses in advance, you can ensure that the shipping information is accurate and complete, reducing the risk of delivery issues and improving overall shipping efficiency. Providing the carrier helps to tailor the address validation process according to specific carrier requirements. Using additional validation methods can further enhance the accuracy of the address verification. The default Sendcloud validation, will always be applied, has in 2 steps: 1. checks the address against the carrier limits (e.g. maximum length of the address line, existence of the postal code for the country, etc.). see also [Carrier address limits](/docs/addresses/address-field-limits#address-field-limits). 2. optimizes (washes) the address to fit within the carrier limits. (e.g. deduplication of address lines, abbreviations, etc.) responses: '200': description: Address validation successful content: application/json: schema: $ref: '#/components/schemas/address-washer-response' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/errors' examples: Failed: summary: Failed to validate the address value: errors: - detail: This field is required. status: '400' source: pointer: /address/carrier_code code: required parameters: - schema: type: string example: 550e8400-e29b-41d4-a716-446655440000 in: header description: If you are an official Sendcloud Tech Partner, you can provide this additional request header for the system to recognize you. Sendcloud Partner UUID is provided to Sendcloud partners. The token is not required but if the header is set, the system will try to validate it. An unknown UUID will cause the 404 return, whilst an invalid one will return 400. name: Sendcloud-Partner-Id requestBody: content: application/json: schema: $ref: '#/components/schemas/address-washer-request' /shipments/{id}: parameters: - schema: type: string name: id in: path required: true description: The id of the shipment you want to retrieve get: summary: Retrieve a shipment description: This endpoint allows you to retrieve a specific shipment created under your Sendcloud credentials, based on the shipment `id`. x-mint: href: /api/v3/shipments/retrieve-a-shipment tags: - Shipments responses: '200': description: OK content: application/json: schema: description: '' type: object properties: data: $ref: '#/components/schemas/shipment-response' examples: ShipmentResponse: value: data: id: XXX-Shipment-id 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: dhl_express:worldwide/incoterm=dap contract_id: 4195 customs_information: null errors: [] order_number: '1234567890' total_order_price: currency: EUR value: '11.11' parcels: - id: 383707309 status: code: CANCELLED message: Cancelled documents: - type: label size: a6 link: https://panel.sendcloud.sc/api/v3/parcels/383559021/documents/label dimensions: width: '15.00' length: '5.00' height: '20.00' unit: cm weight: value: '1.320' unit: kg tracking_url: https://tracking.eu-central-1-0.sendcloud.sc/forward?carrier=postnl&code=3SYZXG8498635&destination=NL&lang=en-us&source=NL&type=parcel&verification=5642+CV&servicepoint_verification=&created_at=2024-06-06 tracking_number: 3SYZXG8498635 tracking_numbers: - tracking_number: 3SYZXG8498635 - tracking_number: 3SYZXG0000000 additional_carrier_data: awb_tracking_number: null box_number: null created_at: '2024-06-06T17:11:14.616615Z' updated_at: '2024-06-06T17:41:16.998357Z' announced_at: '2024-06-06T17:11:15.247645Z' label_notes: - I live at the blue door - The doorbell isn't working package_type: package 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 manufacturer_product_id: ABC-12345 manufacturer_product_id_std: '01234567890128' 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 '404': description: Not Found operationId: sc-public-v3-scp-get-shipment_by_id security: - HTTPBasicAuth: [] - OAuth2ClientCreds: [] /shipments/{id}/cancel: parameters: - schema: type: string name: id in: path required: true description: ID of the shipment post: tags: - Shipments summary: Cancel a shipment description: Use this endpoint to cancel an announced shipment, if the carrier supports cancellation. x-mint: href: /api/v3/shipments/cancel-a-shipment content: |- You can use this endpoint to **Cancel** an announced shipment. ## Cancelling a shipment When you **cancel** a shipment which is already announced (has shipping labels attached to it), you will still be able to find it via the `id` and the [Retrieve a shipment](/api/v3/shipments/retrieve-a-shipment) endpoint. In the Sendcloud platform, it will appear in your **Cancelled labels** overview. **Insurance Notice**: If you proceed to send a shipment that was initially cancelled, the parcel's insurance coverage will become void, and any insurance claims will not be valid for that shipment. After 42 days, it's no longer possible to cancel a shipment, even if it hasn't been sent. ## Conditions for label cancellation It's not always possible to cancel a shipment whose parcel has already been announced. As a result, cancellation is not guaranteed and may be asynchronous depending on the state of the shipment parcel. When you send a cancellation request via this endpoint, the response will indicate the status of the cancellation request. Each carrier will have different cancellation deadlines. Some carriers do not accept cancellation requests regardless of whether or not the label is cancelled within the deadline. You can find more information about cancellation deadlines on our [help center](https://support.sendcloud.com/hc/en-us/articles/360025143991-How-do-I-cancel-my-shipment-). operationId: sc-public-v3-scp-post-cancel_shipment security: - HTTPBasicAuth: [] - OAuth2ClientCreds: [] responses: '200': description: |- Cancelled - The shipment has been cancelled if all valid conditions apply. content: application/json: schema: $ref: '#/components/schemas/cancel-shipment-status' examples: Cancelled: summary: Successfully Cancelled value: data: status: cancelled message: Shipment has been cancelled '202': description: |- Shipment cancellation has been queued - The shipment having the status of ready to send (1000) will be watched for 14 days and if nothing nothing has changed to the shipment, it will be cancelled. content: application/json: schema: $ref: '#/components/schemas/cancel-shipment-status' examples: Cancelled: summary: Successfully queued for cancellation value: data: status: queued message: Shipment cancellation has been queued '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/errors' examples: ShipmentToBeCancelledNotFound: summary: Shipment not found value: errors: - status: '404' code: not_found detail: Not found '409': description: |- Cancellation rejected - When shipment has the status of 2000 which means it is already cancelled. - After period of 42 days of the shipment being announced we cannot cancel it and will let you know about it through a response message. - When shipment has the status code (11) saying that it’s delivered it will not do anything to the shipment and your request will be rejected. content: application/json: schema: $ref: '#/components/schemas/errors' examples: CancellationRejected: summary: Cancellation rejected value: errors: - status: '409' code: invalid detail: This shipment is already being cancelled. /shipments/{id}/return-portal-url: parameters: - schema: type: string name: id in: path required: true description: ID of the shipment get: summary: Retrieve a return portal URL description: Retrieve a return portal link for a specific shipment using the shipment's id. x-mint: href: /api/v3/shipments/retrieve-a-return-portal-url content: |- The URL which is retrieved will link directly to the shipment in the Sendcloud Return portal, so a **return parcel** can be created immediately based on the outgoing shipment. If no Return portal is configured, or if no brand is connected to the shipment, this endpoint will return an error response with a 404 status code. tags: - Shipments operationId: sc-public-v3-scp-get-return_portal_url security: - HTTPBasicAuth: [] - OAuth2ClientCreds: [] responses: '200': description: OK content: application/json: schema: type: object properties: data: type: object properties: url: type: string format: uri description: The return portal URL for the shipment. minLength: 1 required: - url required: - data examples: ReturnPortalURL: summary: Return portal URL value: data: url: http://mybrand.returns-portal.com/initiate/ '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/errors' examples: ReturnPortalNotFound: summary: Return portal not found value: errors: - status: '404' code: not_found detail: No return portal is configured for this shipment. components: 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. 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 Cursor: in: query name: cursor description: |- The cursor query string is used as the pivot value to filter results. If no value is provided, the first page of results will be returned. To get this value, you must encode the offset, reverse and position into a base64 string. There are 3 possible parameters to encode: - `o`: Offset - `r`: Reverse - `p`: Position For example, `r=1&p=300` encoded as a base64 string would be `cj0xJnA9MzAw`. The query string would then be `cursor=cj0xJnA9MzAw`. schema: type: string example: cj0xJnA9MzAw schemas: 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. 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 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 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 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 required-price: title: Price object description: Price, consisting of a value and currency. allOf: - $ref: '#/components/schemas/Price' - type: object required: - value - currency 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 dhl-express-shipment-extras: title: DHL Express Shipment Extras description: Shipment-level carrier-specific fields accepted when shipping with DHL Express. type: object additionalProperties: false properties: hide_sender: title: Hide Sender description: When `true`, the sender address is omitted from the DHL Express shipping label. When omitted or `null`, the carrier contract's default is used. type: - boolean - 'null' default: null example: true dhl-freight-shipment-extras: title: DHL Freight Shipment Extras description: Shipment-level carrier-specific fields accepted when shipping with DHL Freight. type: object additionalProperties: false properties: tail_lift_loading: title: Tail Lift Loading description: When `true`, a tail lift is requested for loading the shipment at pickup. When omitted or `null`, no tail lift is requested for loading. type: - boolean - 'null' default: false example: true tail_lift_unloading: title: Tail Lift Unloading description: When `true`, a tail lift is requested for unloading the shipment at the delivery address. When omitted or `null`, no tail lift is requested for unloading. type: - boolean - 'null' default: false example: true fixed_delivery_date: title: Fixed Delivery Date description: Requests delivery on a fixed calendar date. When omitted or `null`, no fixed delivery date is sent to the carrier. type: - object - 'null' additionalProperties: false properties: date: title: Date description: The requested fixed delivery date, in `yyyy-mm-dd` format. type: string format: date example: '2026-07-20' required: - date default: null carrier-shipment-extras: title: Carrier Shipment Extras description: | Carrier-specific shipment-level fields. The applicable shape is determined by the carrier resolved from `ship_with`. Only the carriers listed below currently declare shipment-level extras; for all other carriers, this object should be omitted. Unknown fields are rejected with a 400 validation error. type: object oneOf: - title: Default type: object - title: DHL Express $ref: '#/components/schemas/dhl-express-shipment-extras' - title: DHL Freight $ref: '#/components/schemas/dhl-freight-shipment-extras' 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: description: | The value paid by the buyer for the order. $ref: '#/components/schemas/optional-price' 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. When using this field you authorize Sendcloud to automatically correct shipping addresses using third-party address validation services. You understand that these corrections are not guaranteed to be accurate and that you remain responsible for the shipping information used for your shipments. items: $ref: '#/components/schemas/address-validation-method-enum' example: - here carrier_fields: description: | Optional carrier-specific shipment-level fields. The accepted shape depends on the carrier resolved from `ship_with`. $ref: '#/components/schemas/carrier-shipment-extras' required: - to_address 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 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 - returned_goods - personal_use 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: description: Shipper's granted discount amount to user. $ref: '#/components/schemas/optional-price' freight_costs: description: Charges associated with the transportation of the goods to their destination paid by the receiver. $ref: '#/components/schemas/optional-price' insurance_costs: description: The costs of insurance coverage for the goods during transit paid by the receiver. $ref: '#/components/schemas/optional-price' other_costs: description: Additional costs or charges associated with the shipment that are not covered by freight and insurance paid by the receiver. $ref: '#/components/schemas/optional-price' 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 customs-information: title: CustomsInformation type: object allOf: - $ref: '#/components/schemas/customs-information-with-optional-fields' - required: - invoice_number - export_reason 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 service-point-request: title: Service Point description: |- Node for service point information. Use the [Retrieve a list of service points](/api/v3/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' earliest_delivery_time: type: - string - 'null' pattern: ^([01]\d|2[0-3]):[0-5]\d$ description: The earliest local time of day the order should be delivered, in `HH:MM` format (minute precision, no seconds or timezone offset). Optional, but if present, `latest_delivery_time` must also be present. example: '09:00' latest_delivery_time: type: - string - 'null' pattern: ^([01]\d|2[0-3]):[0-5]\d$ description: The latest local time of day the order should be delivered, in `HH:MM` format (minute precision, no seconds or timezone offset). Optional, but if present, `earliest_delivery_time` must also be present. example: '17:00' 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 dimension-units: type: string title: Dimensional units enum: - cm - mm - m - yd - ft - in example: mm 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 weight-units: type: string title: Mass Units Object enum: - kg - g - lbs - oz example: g 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 dynalogic-parcel-extras: title: Dynalogic Parcel Extras description: Parcel-level carrier-specific fields accepted when shipping with Dynalogic. type: object additionalProperties: false properties: collo_barcode: title: Collo Barcode description: Optional override for the collo barcode reported to Dynalogic. When omitted or `null`, the parcel ID is used as the collo barcode. type: - string - 'null' maxLength: 32 default: null example: ABC123 chronopost-parcel-extras: title: Chronopost Parcel Extras description: Parcel-level carrier-specific fields accepted when shipping with Chronopost. type: object additionalProperties: false properties: expiration_date: title: Expiration Date description: Best-before date of the parcel's contents, in `yyyy-mm-dd` format. Required when shipping with a Chronopost Chrono Fresh product, in which case it must be at least 5 days from the current date; ignored for other Chronopost products. When omitted or `null`, no expiration date is sent to the carrier. type: - string - 'null' pattern: ^\d{4}-\d{2}-\d{2}$ default: null example: '2026-07-20' carrier-parcel-extras: title: Carrier Parcel Extras description: | Carrier-specific parcel-level fields. The applicable shape is determined by the carrier resolved from `ship_with`. Only the carriers listed below currently declare parcel-level extras; for all other carriers, this object should be omitted. Unknown fields are rejected with a 400 validation error. type: object oneOf: - title: Default type: object - title: Dynalogic $ref: '#/components/schemas/dynalogic-parcel-extras' - title: Chronopost $ref: '#/components/schemas/chronopost-parcel-extras' 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 carrier_fields: description: | Optional carrier-specific parcel-level fields. The accepted shape depends on the carrier resolved from `ship_with`. $ref: '#/components/schemas/carrier-parcel-extras' 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 cpsc-certification: title: CPSC certification type: object description: CPSC (Consumer Product Safety Commission) certificate details for a single product. properties: product_id: type: string description: CPSC product identifier. example: '12345' certifier_id: type: string description: CPSC certifier identifier. example: '67890' version_id: type: string description: CPSC certificate version identifier. example: '1' required: - product_id - certifier_id - version_id 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 example: item_id: '5552' description: T-Shirt XL quantity: 1 weight: value: 0.5 unit: kg price: value: '10.00' currency: EUR hs_code: '620520' origin_country: NL sku: TS1234 cpsc: product_id: '12345' certifier_id: '67890' version_id: '1' 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: description: Weight of the item. $ref: '#/components/schemas/weight' price: description: Price of the item. $ref: '#/components/schemas/required-price' hs_code: type: string description: Harmonized System Code. example: '620520' maxLength: 12 origin_country: type: string description: ISO-2 code of the country where the items were originally produced. 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' cpsc: description: CPSC (Consumer Product Safety Commission) certification details required for certain shipments to the United States. Omit this field entirely if not applicable. anyOf: - type: 'null' - $ref: '#/components/schemas/cpsc-certification' 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 manufacturer_product_id: title: Manufacturer Product ID type: - string - 'null' description: A manufacturer or product supplier's unique code, assigned to an individual product. maxLength: 70 example: ABC-12345 manufacturer_product_id_std: title: Manufacturer Product ID (Standardized) type: - string - 'null' description: A standardized manufacturer product identifier assigned by a global industry standard body (e.g. GTIN). Provide only if one exists for the product. maxLength: 70 example: '01234567890128' properties: type: object additionalProperties: true description: Any custom user-defined properties of order item or product example: size: red color: green parcel-item-domestic: title: Domestic parcel item description: A single item in a domestic shipment - one that does not cross a customs border and does not require custom documents. All customs fields are optional. allOf: - $ref: '#/components/schemas/parcel-item' - type: object properties: quantity: description: Quantity of items shipped. Defaults to `1` if not provided. default: 1 weight: description: Weight of the item. Defaults to `0.001 kg` if not provided. default: value: 0.001 unit: kg price: description: Price of the item. The price value defaults to `0.00` if not provided. parcel-item-international: title: International parcel item description: A single item in an international shipment - one that crosses a customs border (e.g. EU to non-EU) and requires customs documents. `description`, `quantity`, `weight`, `price`, `hs_code`, and `origin_country` are required for customs document generation. allOf: - $ref: '#/components/schemas/parcel-item' - required: - description - quantity - weight - price - hs_code - origin_country 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: oneOf: - $ref: '#/components/schemas/parcel-item-domestic' - $ref: '#/components/schemas/parcel-item-international' shipment-request-sync-announce: title: Synchronous Announcement Shipment request Object description: Synchronous Announcement Shipment request object model type: object allOf: - $ref: '#/components/schemas/shipment-request' - type: object properties: parcels: description: |- Represents each package of the shipment. Note that you can send a maximum of 15 parcels per shipment to this endpoint. To announce more than 15 parcels in the same shipment, you can use the [Create and announce a shipment asynchronously](/api/v3/shipments/create-and-announce-a-shipment-asynchronously) endpoint. Note: each carrier can have a lower than the default number of parcels limit per shipment. type: array items: $ref: '#/components/schemas/parcel-common' minItems: 1 maxItems: 15 - required: - parcels 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 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. 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: description: The sender address for the shipment. $ref: '#/components/schemas/address-with-required-fields' 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' 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 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. tracking-numbers: title: Tracking Number Object type: object description: A tracking number belonging to the parcel properties: tracking_number: type: string description: Tracking number of the shipment. example: 3SYZXG8498635 parcel-item-response: title: Parcel Item Response Object description: A single item in a shipment as returned in API responses. All fields are always populated by the backend. type: object allOf: - $ref: '#/components/schemas/parcel-item' - required: - hs_code - weight - description - price - quantity 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 tracking_numbers: type: array description: All tracking numbers known for this parcel. readOnly: true items: $ref: '#/components/schemas/tracking-numbers' 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 - type: object properties: parcel_items: type: array items: $ref: '#/components/schemas/parcel-item-response' sync-parcels-array-response: title: Sync Parcels Array Response Object description: Sync parcel common object model type: object allOf: - $ref: '#/components/schemas/parcels-array-response' - type: object properties: label_file: type: - string - 'null' format: byte description: The base64 representation of the label file. **Note that it will be returned if there is only one parcel in the shipment.** sync-shipment-response: title: Sync shipment response Object description: Sync shipment response object model allOf: - $ref: '#/components/schemas/base-shipment-response' - properties: parcels: description: Represents each package of the shipment. type: array items: $ref: '#/components/schemas/sync-parcels-array-response' label_details: $ref: '#/components/schemas/label-details' type: object 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-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' 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 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-request-with-optional-fields: title: Shipment request with optional fields Object description: Shipment request with optional fields object model allOf: - $ref: '#/components/schemas/shipment-common-with-optional-fields' - type: object 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' customs_information: $ref: '#/components/schemas/customs-information-with-optional-fields' - type: object properties: to_service_point: $ref: '#/components/schemas/service-point-request' - type: object properties: 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-with-optional-fields: title: Parcels array request with optional fields Object description: Parcels array request with optional fields object model type: object properties: parcels: description: Represents each package of the shipment. Each carrier can have its own number of parcels limit per shipment, otherwise there is a restriction to a maximum of 50 parcels (default). type: array items: allOf: - $ref: '#/components/schemas/parcel-common-with-optional-fields' - 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: oneOf: - $ref: '#/components/schemas/parcel-item-domestic' - $ref: '#/components/schemas/parcel-item-international' minItems: 1 maxItems: 50 shipment-request-with-rules: title: Asynchronous Announcement Shipment with Rules request Object description: Asynchronous Shipment with Rules request object model type: object allOf: - $ref: '#/components/schemas/shipment-request-with-optional-fields' - $ref: '#/components/schemas/multicollo-parcels-array-request-with-optional-fields' - type: object properties: apply_shipping_defaults: type: boolean description: |- When set to `true`, the "Default weight", "Preferred shipping method" and "Default export reason" [shipping defaults](https://app.sendcloud.com/v2/shipping/shipping-defaults) will be applied, if they were not provided by the request payload. **Note that the request payload values and shipping rules take precedence over these defaults.** default: true example: true apply_shipping_rules: type: boolean description: |- When set to `true`, [shipping rules](https://app.sendcloud.com/v2/shipping/rules) will be applied. **Note that rules take precedence over the values provided in the request payload and over the [shipping defaults](https://app.sendcloud.com/v2/shipping/shipping-defaults).** For instance, if a contract is specified in one of the applicable rules for the shipment that is being requested, the contract value provided in the request payload will be ignored. Also keep in mind that since orders created by the API do not appear in the Sendcloud platform's Incoming Orders overview, not all shipping rules can be applied. default: true example: true delivery_indicator: type: string description: | Free text that is intended for applying the **Checkout Delivery Method** condition in shipping rules. Learn more about [Shipping rules](/docs/shipping/shipping-rules/). example: DHL home delivery applied-shipping-rule: title: Applied shipping rule modification description: Represents a shipping rule that was applied to the shipment and the result of the changes it made. type: object properties: rule: type: object description: The shipping rule that was applied. properties: id: type: integer description: The unique identifier of the shipping rule. example: 315157 name: type: string description: The name of the shipping rule. example: Ship with PostNL for NL required: - id - name result: type: object description: |- The changes that were applied by the shipping rule. The keys represent the fields that were modified and the values represent the new values. Possible keys: `additional_declaration_statements`, `box`, `change_return_fee`, `contract`, `email`, `hs_code`, `number_of_shipments`, `origin_country`, `telephone`, `sender_address`, `shipping_option_code`, `total_insured_value`, `disable_return_requests`, `weight`. additionalProperties: true example: shipping_option_code: postnl:standard required: - rule - result sync-shipment-with-rules-response: title: Sync shipment with rules response Object description: Sync shipment response object model including applied shipping rules. allOf: - $ref: '#/components/schemas/base-shipment-response' - properties: parcels: description: Represents each package of the shipment. type: array items: $ref: '#/components/schemas/sync-parcels-array-response' label_details: $ref: '#/components/schemas/label-details' applied_shipping_rules: description: List of shipping rules that were applied to the shipment and the result of each rule's modifications. type: array items: $ref: '#/components/schemas/applied-shipping-rule' type: object shipment-with-rules-response: title: Shipment with rules response Object description: Shipment response object model including applied shipping rules. 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' applied_shipping_rules: description: List of shipping rules that were applied to the shipment and the result of each rule's modifications. type: array items: $ref: '#/components/schemas/applied-shipping-rule' raw-address: title: Raw address type: object description: Raw address object properties: 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 address-washer-request: title: Address Washer Request description: Address Washer Request object model type: object properties: address: $ref: '#/components/schemas/raw-address' carrier_code: description: The code of the carrier to be used for the address validation. Only carriers available to your account can be used. type: string example: trunkrs validation_methods: description: | An array of optional address validation methods to be applied The default Sendcloud validation will always be applied. type: array items: $ref: '#/components/schemas/address-validation-method-enum' example: - here required: - address - carrier_code address-washer-response: title: Address Washer Response description: Address Washer Response object model type: object properties: input_address_is_valid: anyOf: - type: boolean - type: 'null' description: Indicates if the input address is valid. In case null is returned, the address is not valid and the details are not available (f.e.the address validator is not available). results: description: The results of the address validation. type: array items: type: object properties: address: description: The validated address details. In case null is returned, the address is not valid and the details are not available (f.e.the address validator is not available). anyOf: - $ref: '#/components/schemas/raw-address' - type: 'null' validation_method: description: The method used for address validation, null stands for the Sendcloud address carrier optimizer validation method. anyOf: - $ref: '#/components/schemas/address-validation-method-enum' - type: 'null' recommended: type: boolean description: Indicates if the address is recommended after validation. analysis: anyOf: - type: object description: Analysis details of the address validation process. In case null is returned no analysis details are available. properties: validation_result: type: object description: The result of the validation process. properties: is_valid: type: boolean description: Indicates if the address is valid. reasons: type: array description: List of reasons for the validation result. items: type: string oneOf: - const: ADDRESS_TOO_LONG title: address_lines:too_long description: The address line exceeds the maximum length. - const: HOUSE_NUMBER_TOO_LONG title: house_number:too_long description: The house number exceeds the maximum length. - const: HOUSE_NUMBER_TOO_SHORT title: house_number:too_short description: The house number is too short. - const: ADDRESS_NOT_VALID title: address:does_not_exist description: The address does not exist. - const: COUNTRY_CODE_MISSING title: country_code:missing description: The country code is missing. - const: POSTAL_CODE_MISSING title: postal_code:missing description: The postal code is missing. - const: STATE_MISSING title: state:missing description: The state is missing. - const: PROVINCE_MISSING title: province:missing description: The province is missing. changed_attributes: type: array description: List of changed attributes. items: type: string invalid_attributes: type: array description: List of attributes that are invalid (i.e. below the field-level validation threshold). items: type: string - type: 'null' cancellation-status: title: Cancel Shipment Status Object type: object properties: status: type: string minLength: 1 example: cancelled message: type: string minLength: 1 example: Shipment has been cancelled required: - status - message cancel-shipment-status: title: Cancel Shipment Status object type: object properties: data: $ref: '#/components/schemas/cancellation-status' required: - data