openapi: 3.1.0 info: title: Address Shipments API 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 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 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 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 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 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: '' 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: '' 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_url: null additional_carrier_data: awb_tracking_number: null box_number: null label_file: null - parcel_items: - origin_country: NL hs_code: '12345677' price: value: '7.65' currency: EUR weight: value: 0.3 unit: kg description: T-Shirt L quantity: 1 product_id: '19284' mid_code: NLOZR92MEL material_content: 100% Cotton intended_use: Personal use dds_reference: 25FIYPEK0A7573 taric_doc_code: Y142 item_id: '5552' properties: size: XL color: green sku: TS1235 dimensions: width: '20.00' length: '10.00' height: '30.00' unit: cm weight: value: '2.320' unit: kg created_at: '2024-10-30T14:02:30.844592Z' updated_at: '2024-10-30T14:02:30.844592Z' announced_at: null id: 427189742 status: code: ANNOUNCING message: Being announced documents: [] tracking_number: '' tracking_url: null additional_carrier_data: awb_tracking_number: null box_number: null label_file: null order_number: '1234567890' total_order_price: value: '11.11' currency: EUR brand_id: null carrier: code: postnl name: PostNL errors: [] '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/errors' examples: Failed: summary: Failed to create shipment (with a single parcel) value: errors: - detail: This field is required. status: '400' source: pointer: /data/attributes/to_address/name code: required '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/errors' examples: NotFound: summary: Partner ID was not found. value: errors: - title: Not found detail: The partner ID was not found. status: '404' code: not_found 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.\n\nIf no shipping rules or defaults are configured to automatically assign the fields listed below, those fields must be provided to create a shipment successfully:\n- `from_address` (from Ship with address)\n- `ship_with` (from Ship with)\n- `parcels` (from Set number of parcels)\n\n**Note: the shipment (parcels) will be linked to the integration identified by the API credentials you supply as request authentication (`Basic ...`).**\n\n## Shipping rules\n\n- **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.**\n- **Shipping rules do not fully apply to multicollo shipments.\n 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.\n Additionally, the following actions will not be triggered:**\n - Using a box (Use box)\n - Setting the weight (Set weight)\n - Setting the number of parcels (Set number of parcels)\n - Insuring the shipment value (Insure shipment value by)\n - Insuring it by percentage (Insure shipment value by %)\n - Increasing item value by percentage (Decrease item value by %)\n - Setting item HS code (Set Item HS Code)\n - Setting item name (Set item name)\n - Setting item origin country (Set Item Origin Country)\n - Setting item value (Set item value)\n - Setting item weight (Set item weight)\n\n**Please consider these limitations when defining rules.**\n\n### Shipping rules conditions (IF) that can be applied\n\n- Carrier\n- Checkout delivery method\n- Company name\n- Customer email\n- Integration\n- Item SKU\n- Item name\n- Item quantity\n- Parcel height (cm)\n- Parcel length (cm)\n- Parcel width (cm)\n- Phone number\n- Postal code\n- To country\n- Total order value\n- Total parcel item value\n- Weight (kg)\n\n## Shipping rules actions (THEN) that can be applied\n\n- Add customs declaration statement\n- Use box\n- Decrease item value by %\n- Insure shipment value by\n- Insure shipment value by %\n- Set customs general notes\n- Set customer email\n- Set Item HS Code\n- Set item name\n- Set Item Origin Country\n- Set item value\n- Set item weight\n- Set number of parcels\n- Phone number\n- Ship with address\n- Ship with\n- Set weight\n- 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 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 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 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 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.\n\nIf no shipping rules or defaults are configured to automatically assign the fields listed below, those fields must be provided to create a shipment successfully: \n- `from_address` (from Ship with address)\n- `ship_with` (from Ship with)\n- `parcels` (from Set number of parcels)\n\n**Note: the shipment (parcels) will be linked to the integration identified by the API credentials you supply as request authentication (`Basic ...`).**\n\n## Shipping rules\n\n- **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.**\n- **Shipping rules do not fully apply to multicollo shipments.\n 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.\n Additionally, the following actions will not be triggered:**\n - Using a box (Use box)\n - Setting the weight (Set weight)\n - Setting the number of parcels (Set number of parcels)\n - Insuring the shipment value (Insure shipment value by)\n - Insuring it by percentage (Insure shipment value by %)\n - Increasing item value by percentage (Decrease item value by %)\n - Setting item HS code (Set Item HS Code)\n - Setting item name (Set item name)\n - Setting item origin country (Set Item Origin Country)\n - Setting item value (Set item value)\n - Setting item weight (Set item weight)\n\n**Please consider these limitations when defining rules.**\n\n### Shipping rules conditions (IF) that can be applied\n\n- Carrier\n- Checkout delivery method\n- Company name\n- Customer email\n- Integration\n- Item SKU\n- Item name\n- Item quantity\n- Parcel height (cm)\n- Parcel length (cm)\n- Parcel width (cm)\n- Phone number\n- Postal code\n- To country\n- Total order value\n- Total parcel item value\n- Weight (kg)\n\n## Shipping rules actions (THEN) that can be applied\n\n- Add customs declaration statement\n- Use box\n- Decrease item value by %\n- Insure shipment value by\n- Insure shipment value by %\n- Set customs general notes\n- Set customer email\n- Set Item HS Code\n- Set item name\n- Set Item Origin Country\n- Set item value\n- Set item weight\n- Set number of parcels\n- Phone number\n- Ship with address\n- Ship with\n- Set weight\n- 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: '' 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: '' 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_url: null additional_carrier_data: awb_tracking_number: null box_number: null label_file: null - parcel_items: - origin_country: NL hs_code: '12345677' price: value: '7.65' currency: EUR weight: value: 0.3 unit: kg description: T-Shirt L quantity: 1 product_id: '19284' mid_code: NLOZR92MEL material_content: 100% Cotton intended_use: Personal use dds_reference: 25FIYPEK0A7573 taric_doc_code: Y142 item_id: '5552' properties: size: XL color: green sku: TS1235 dimensions: width: '20.00' length: '10.00' height: '30.00' unit: cm weight: value: '2.320' unit: kg created_at: '2024-10-30T14:02:30.844592Z' updated_at: '2024-10-30T14:02:30.844592Z' announced_at: null id: 427189742 status: code: ANNOUNCING message: Being announced documents: [] tracking_number: '' tracking_url: null additional_carrier_data: awb_tracking_number: null box_number: null label_file: null order_number: '1234567890' total_order_price: value: '11.11' currency: EUR brand_id: 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 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: - 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.\nBy validating addresses in advance, you can ensure that the shipping information is accurate and complete,\nreducing the risk of delivery issues and improving overall shipping efficiency.\nProviding the carrier helps to tailor the address validation process according to specific carrier requirements.\nUsing additional validation methods can further enhance the accuracy of the address verification.\n\nThe default Sendcloud validation, will always be applied, has in 2 steps:\n1. checks the address against the carrier limits\n(e.g. maximum length of the address line, existence of the postal code for the country, etc.). \nsee also [Carrier address limits](/docs/shipments/address-field-limits#address-field-limits).\n\n2. optimizes (washes) the address to fit within the carrier limits.\n(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/shipments/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 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.\n\n## Cancelling a shipment\n\nWhen 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.\n\n**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.\n\n\n After 42 days, it's no longer possible to cancel a shipment, even if it hasn't been sent.\n\n\n## Conditions for label cancellation\n\nIt'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.\n\n\n 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-).\n" 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. /integrations/{id}/shipments: parameters: - name: id in: path required: true schema: type: integer description: The id of the integration to which the shipments belong get: operationId: sc-public-v2-orders-get-retrieve_a_list_of_shipments security: - HTTPBasicAuth: [] - OAuth2ClientCreds: [] x-mint: href: /api/v2/integrations/retrieve-a-list-of-shipments content: "\n **API v2 is entering maintenance mode.** New users should start with API v3 to access our latest features and improved performance. Already using v2? Don't worry, your current integration remains fully functional. Read more about [maintenance mode](/docs/getting-started/api-version-guide), or check out the [migration guide for API v3](/docs/getting-started/migration-guidelines-for-api-v3).\n\n\nNote that the orders **are not** affected by [shipping rules](https://support.sendcloud.com/hc/en-us/articles/360025143571-Automate-your-workflow-using-Sendcloud-Shipping-Rules) at the time of retrieval, unless enabled explicitly.\n\nThis endpoint is paginated, meaning that you can navigate through the `results` via the URLs provided within the `next` and `previous` fields." x-sendcloud-paginated: true x-sendcloud-paginated-discriminator: results description: Retrieve a list of orders that were imported from a specific webshop integration. parameters: - $ref: '#/components/parameters/cursor-parameter' - name: start_date in: query required: false description: Displays orders from the given `start_date`, including the set date. It defaults to one year ago. schema: type: string format: date - name: end_date in: query required: false description: Displays orders up to the given `end_date`, including the set date. It defaults to the current date. schema: type: string format: date - name: external_order_ids in: query required: false description: Filters results to shipments where their `external_order_id` matches one of the user provided ones. schema: type: array items: type: string - name: external_shipment_ids in: query required: false description: Filters results to shipments where their `external_shipments_id` matches one of the user provided ones. schema: type: array items: type: string - name: shipping_rules in: query required: false description: Enable shipping rules when retrieving orders. This will have an impact on the `allowed_shipping_methods`. schema: type: boolean - name: order_number in: query required: false description: Filters results to shipments on `order_number`. schema: type: string - name: sender_address in: query required: false description: Allows to specify a sender address id to display proper `allowed_shipping_methods`. schema: type: integer responses: '200': description: OK content: application/json: schema: type: object properties: next: type: string format: uri description: Cursor based pagination url to go forward. By following this URL you can get a next batch of shipments previous: type: string format: uri description: Cursor based pagination url to go backwards. By following this URL you can get a previous batch of shipments results: type: array items: $ref: '#/components/schemas/ShipmentBlobOrder' examples: RetrieveShipmentList: summary: Retrieve a list of shipments value: next: https://example.com previous: https://example.com results: - address: Lansdown Glade address_2: string allowed_shipping_methods: - 0 barcode: string city: Oss company_name: string country: AW created_at: '2019-08-24T14:15:22Z' currency: EUR customs_invoice_nr: '120' customs_shipment_type: 0 email: user@example.com external_order_id: '555413' external_shipment_id: '777413' house_number: '15' integration: 0 name: John Doe order_number: OXSDFGHTD-12 order_status: id: fulfilled message: Fulfilled parcel_items: - description: Very orange color hs_code: '01013000' origin_country: AW product_id: '1458734634' properties: size: small colour: red quantity: 2 sku: WW-DR-GR-XS-001 value: '3.5' weight: '1' mid_code: NLOZR92MEL material_content: 100% Cotton intended_use: Personal use payment_status: id: paid message: Paid postal_code: '5341' sender_address: 12345 shipment_uuid: 6b436cb2-65a4-482c-9d25-38be7868ff00 shipping_method: 12345 shipping_method_checkout_name: string telephone: string to_post_number: string to_service_point: 0 to_state: string total_order_value: string updated_at: '2019-08-24T14:15:22Z' weight: string checkout_payload: sender_address_id: 0 shipping_product: code: postnl:standard name: PostNL Standard selected_functionalities: age_check: 18 last_mile: home_delivery first_mile: pickup_dropoff multicollo: true form_factor: parcel service_area: domestic weekend_delivery: saturday delivery_deadline: best_effort direct_contract_only: false delivery_method_type: string delivery_method_data: delivery_date: '2019-08-24T14:15:22Z' formatted_delivery_date: string parcel_handover_date: '2019-08-24T14:15:22Z' width: string height: string length: string customs_details: discount_granted: '3.99' insurance_costs: '9.99' freight_costs: '5.99' other_costs: '2.99' tax_numbers: sender: - tax_number: name: VAT country: NL value: NL987654321B02 receiver: - tax_number: name: VAT country: DE value: DE123456789B03 importer_of_records: - tax_number: name: VAT country: NL value: NL975318642B01 shipment_created_at: '2019-09-25T14:15:22Z' shipment_updated_at: '2019-09-25T14:15:22Z' '404': $ref: '#/components/responses/404-Shipments' summary: Retrieve a list of shipments tags: - Shipments post: operationId: sc-public-v2-orders-post-create_a_list_of_shipments security: - HTTPBasicAuth: [] - OAuth2ClientCreds: [] x-mint: href: /api/v2/integrations/create-a-list-of-shipments content: "\n **API v2 is entering maintenance mode.** New users should start with API v3 to access our latest features and improved performance. Already using v2? Don't worry, your current integration remains fully functional. Read more about [maintenance mode](/docs/getting-started/api-version-guide), or check out the [migration guide for API v3](/docs/getting-started/migration-guidelines-for-api-v3).\n\n\n\n This endpoint is only available for official Sendcloud partners.\n\n\nThis endpoint allows you to insert shipments (or 'orders') into an API integration from your shop system, and have them appear in your Sendcloud account. Imported orders will appear in the Sendcloud platform under the **Incoming order overview** with the status \"Ready to process\". This allows you to easily generate parcels and create shipping labels via the API or directly from the Sendcloud platform. The validation for this endpoint is more relaxed, therefore we recommend this method over the [Create a parcel or parcels](/api/v2/parcels/create-a-parcel-or-parcels) endpoint for third-party integrators.\n\nThis is an **UPSERT** endpoint which attempts to be idempotent given specific fields to ensure that orders are not duplicated. If there's an existing match in our database for specific fields (`external_order_id` and `external_shipment_id`), then the shipment will be updated. The system will only update orders that have had their `updated_at` (ISO 8601 DateTime) timestamp changed.\n\nThe `external_shipment_id` field is used to split orders across multiple shipments, however, this field is not supported by all shop systems. If your shop system supports the distribution of product items within an order across multiple shipments, you can use the shipment data to create multiple entries. If your shop does not support this feature, you can set the `external_shipment_id` value to `null`.\n\nBatches are limited to 100 orders at once. This endpoint should accept most values in any of the available fields, but in the case of erroneous data, an error message will be returned directly. Your requests should almost always succeed unless the field structure is not correct." description: Insert shipments (or 'orders') into an API integration from your shop system, and have them appear in your Sendcloud account. responses: '200': description: 'List with references to created shipments, or the errors that occurred while creating the shipment. When a shipment can''t be created, the response will contain an entry for the object with the errors. This object will have a path to each field containing errors, listing the error(s) it contains.' content: application/json: schema: type: array items: oneOf: - $ref: '#/components/schemas/ShipmentCreateUpdateLog' - $ref: '#/components/schemas/ShipmentErrorLog' examples: CreateUpdateShipments: summary: Create or update a list of shipments value: - external_order_id: '1175584' external_shipment_id: '777413' shipment_uuid: 6b436cb2-65a4-482c-9d25-38be7868ff00 status: created - error: checkout_payload: delivery_method_data: delivery_date: - This field is required. external_order_id: '1184635' external_shipment_id: '' status: error '400': description: Bad Request '404': $ref: '#/components/responses/404-Shipments' summary: Create or update a list of shipments tags: - Shipments requestBody: content: application/json: schema: type: array items: $ref: '#/components/schemas/ShipmentBlobOrderCreate' examples: CreateUpdateShipments: summary: Create or update a list of shipments value: - address: Lansdown Glade address_2: string city: Oss company_name: string country: AW created_at: '2019-08-24T14:15:22Z' currency: EUR customs_invoice_nr: '120' customs_shipment_type: 0 email: user@example.com external_order_id: '555413' external_shipment_id: '777413' house_number: '15' name: John Doe order_number: OXSDFGHTD-12 order_status: id: fulfilled message: Fulfilled parcel_items: - description: Very orange color hs_code: '01013000' origin_country: AW product_id: '1458734634' properties: size: small colour: red quantity: 2 sku: WW-DR-GR-XS-001 value: '3.5' weight: '1' mid_code: NLOZR92MEL material_content: 100% Cotton intended_use: Personal use payment_status: id: paid message: Paid postal_code: '5341' shipping_method: 12345 shipping_method_checkout_name: string telephone: string to_post_number: string to_service_point: 0 to_state: string total_order_value: string updated_at: '2019-08-24T14:15:22Z' weight: string checkout_payload: sender_address_id: 0 shipping_product: code: postnl:standard name: PostNL Standard selected_functionalities: age_check: 18 last_mile: home_delivery first_mile: pickup_dropoff multicollo: true form_factor: parcel service_area: domestic weekend_delivery: saturday delivery_deadline: best_effort direct_contract_only: false delivery_method_type: string delivery_method_data: delivery_date: '2019-08-24T14:15:22Z' formatted_delivery_date: string parcel_handover_date: '2019-08-24T14:15:22Z' width: string height: string length: string customs_details: discount_granted: '3.99' insurance_costs: '9.99' freight_costs: '5.99' other_costs: '2.99' tax_numbers: sender: - tax_number: name: VAT country: NL value: NL987654321B02 receiver: - tax_number: name: VAT country: DE value: DE123456789B03 importer_of_records: - tax_number: name: VAT country: NL value: NL975318642B01 description: '' /integrations/{id}/shipments/delete: parameters: - schema: type: integer name: id in: path required: true description: The id of the integration to which the shipments belong post: tags: - Shipments summary: Delete a shipment operationId: sc-public-v2-orders-post-delete_a_shipment security: - HTTPBasicAuth: [] - OAuth2ClientCreds: [] x-mint: href: /api/v2/integrations/delete-a-shipment content: "\n **API v2 is entering maintenance mode.** New users should start with API v3 to access our latest features and improved performance. Already using v2? Don't worry, your current integration remains fully functional. Read more about [maintenance mode](/docs/getting-started/api-version-guide), or check out the [migration guide for API v3](/docs/getting-started/migration-guidelines-for-api-v3).\n\n\nThe `order_status` and `payment_status` fields we retrieve from integrations are not mapped in our system, meaning that orders will not be automatically updated or deleted if the values for these fields change after an order is placed.\n\nYou can delete an order by providing either a `shipment_uuid`, or a combination of the `external_order_id` and `external_shipment_id` properties." description: Allows you to delete a shipment from Sendcloud, e.g. if it has been canceled or deleted in your shop system. requestBody: description: You must provide either a shipment_uuid or the combination of external_order_id and external_shipment_id to this endpoint. content: application/json: schema: oneOf: - type: object properties: shipment_uuid: type: string format: uuid description: Autogenerated Sendcloud's internal ID required: - shipment_uuid - type: object properties: external_order_id: type: string description: External order ID assigned by shop system external_shipment_id: type: string description: External shipment ID assigned by shop system required: - external_order_id - external_shipment_id examples: DeleteByUUID: summary: Delete a shipment (via UUID) value: shipment_uuid: 39874b59-2a68-4a3d-8e00-aeb9e0540d00 DeleteByOrderIdShipmentId: summary: Delete a shipment (via `order_id` and `shipment_id`) value: external_order_id: '123457' external_shipment_id: S00002 responses: '204': description: No Content '400': description: Bad Request content: application/json: schema: type: object properties: error: type: object properties: code: type: integer request: type: string message: type: string examples: RequiredFieldMissing: summary: Missing required fields value: error: code: 400 request: api/v2/integrations/1234/shipments/delete message: Missing shipment_uuid or the pair external_order_id and external_shipment_id invalid_uuid: summary: Invalid UUID value: error: code: 400 request: api/v2/integrations/1234/shipments/delete message: Must be a valid UUID. '404': $ref: '#/components/responses/404-Shipments' components: schemas: 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 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 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 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 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 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 parcels-array-response: title: Parcels Array Response Object description: Parcel common object model type: object allOf: - $ref: '#/components/schemas/parcel-common' - type: object properties: created_at: type: string format: date-time description: The timestamp of when the parcel was created readOnly: true example: '2024-09-04T12:14:36.506925Z' updated_at: type: string format: date-time description: The timestamp of when the parcel was last updated readOnly: true example: '2024-09-04T12:14:47.203107Z' announced_at: type: - string - 'null' description: The timestamp of when the parcel was announced to the carrier (label was created) format: date-time readOnly: true example: '2024-09-04T12:14:47.153985Z' id: type: integer description: ID of the parcel (required to retrieve a parcel document for async announcement) readOnly: true status: $ref: '#/components/schemas/status' readOnly: true documents: type: array uniqueItems: true description: An array of documents. A parcel can contain multiple documents, for instance labels and a customs form. This field returns an array of all the available documents for this parcel. readOnly: true items: $ref: '#/components/schemas/documents' tracking_number: type: string description: Tracking number of the shipment. readOnly: true example: 3SYZXG8498635 tracking_url: type: - string - 'null' description: Tracking url of this shipment. readOnly: true additional_carrier_data: type: object title: Carrier-specific data readOnly: true description: Specific data that only belongs to some carriers. properties: awb_tracking_number: type: - string - 'null' description: Deutsche Post Global Mail only. This indicates the air waybill number of this box of Global Mail parcels. This will be set once the `Finalize box` has been called. box_number: type: - integer - 'null' description: Deutsche Post Global Mail only. This indicates the box to which this parcel belongs. This will be only set for Global Mail parcels. label_notes: type: - array - 'null' description: Custom messages printed on the shipping label. Use this field to include custom text - such as invoice numbers, product IDs, or internal reference codes - on the package’s shipping label. maxItems: 255 items: type: string example: The doorbell isn’t working minLength: 1 maxLength: 255 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 ShipmentBlobOrderCreate: title: Shipment Blob Order Create Object type: object properties: address: title: Address type: string minLength: 1 address_2: title: Address 2 type: string minLength: 0 city: title: City type: string minLength: 1 company_name: title: Company name type: string minLength: 0 country: $ref: '#/components/schemas/country-codes' created_at: type: string title: Created at format: date-time description: Timestamp indicating when the shipment was created in the shop system. This value will be saved and accessible through `shipment_created_at` field in GET response. example: '2022-05-07T15:08:12.152000Z' currency: type: - string - 'null' title: Currency minLength: 1 description: ISO 4217 currency code enum: - EUR - USD - GBP customs_invoice_nr: type: string title: Customs invoice nr minLength: 0 description: Your own commercial invoice number example: '120' customs_shipment_type: type: - integer - 'null' title: Customs shipment type enum: - 0 - 1 - 2 - 3 - 4 description: "Type of shipment for customs purposes:\n - `0` - Gift\n - `1` - Documents\n - `2` - Commercial Goods\n - `3` - Commercial Sample\n - `4` - Returned Goods\n" minimum: 0 maximum: 4 email: title: Customer email address type: string format: email minLength: 0 external_order_id: title: External order id type: string minLength: 1 description: External order ID assigned by the shop system external_shipment_id: title: External shipment id type: - string - 'null' minLength: 1 description: External shipment ID assigned by the shop system house_number: title: House number type: string minLength: 0 name: title: Name type: string minLength: 1 order_number: title: Order number type: string minLength: 1 description: Unique order number generated manualy or by the shop system order_status: $ref: '#/components/schemas/ShipmentBlobStatus' parcel_items: type: - array - 'null' description: List of items the parcel contains items: $ref: '#/components/schemas/ParcelItems' payment_status: $ref: '#/components/schemas/ShipmentBlobStatus' postal_code: title: Postal code type: string minLength: 1 shipping_method: type: - integer - 'null' title: Shipping method description: Foreign key indicating shipping method used example: 1234 shipping_method_checkout_name: title: Shipping method checkout name type: string minLength: 0 maxLength: 100 description: Human readable shipping method name telephone: title: Telephone type: string minLength: 0 to_post_number: title: To post number type: string minLength: 0 to_service_point: title: To service point type: - integer - 'null' to_state: title: To state type: - string - 'null' minLength: 1 total_order_value: title: Total order value type: - string - 'null' format: decimal description: The total price of an order updated_at: type: string title: Updated at format: date-time description: Timestamp indicating when the shipment was updated in the shop system. This value will be saved and accessible through `shipment_updated_at` field in GET response. example: '2022-05-07T15:08:12.152000Z' weight: type: - string - 'null' title: Weight format: decimal description: Total weight of the order. Cannot be smaler than 0.001 example: '10.2' maxLength: 10 checkout_payload: $ref: '#/components/schemas/CheckoutPayload' width: type: - string - 'null' title: Width description: Volumetric weight width format: decimal maxLength: 10 example: '10.2' height: type: - string - 'null' title: Height description: Volumetric weight height format: decimal maxLength: 10 example: '10.2' length: type: - string - 'null' title: Length description: Volumetric weight length format: decimal maxLength: 10 example: '10.2' customs_details: $ref: '#/components/schemas/CustomsInformation' required: - address - address_2 - city - company_name - country - created_at - currency - customs_invoice_nr - customs_shipment_type - email - external_order_id - external_shipment_id - house_number - name - order_number - order_status - parcel_items - payment_status - postal_code - shipping_method_checkout_name - telephone - to_post_number - to_service_point - to_state - updated_at ShipmentCreateUpdateLog: title: Shipment Creation or Update information log type: object properties: external_order_id: title: External Order ID type: string minLength: 1 external_shipment_id: title: External Shipment ID type: string minLength: 1 shipment_uuid: title: Shipment UUID type: string format: uuid minLength: 1 status: title: Status type: string enum: - created - updated 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' parcel-item: title: Parcel Item Object description: A single item in a shipment. **Note that parcel item object is required for shipments that require customs documents.** type: object allOf: - $ref: '#/components/schemas/parcel-item-with-optional-fields' - required: - hs_code - weight - description - price 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 customs-information-with-optional-fields: title: CustomsInformation with optional fields type: - object - 'null' description: Optional customs information that should be provided for international shipments. This information is used for generating customs documents. example: invoice_number: INV-123 export_reason: commercial_goods export_type: private invoice_date: '2023-08-24' discount_granted: value: '14.99' currency: EUR freight_costs: null insurance_costs: value: '3.60' currency: EUR other_costs: value: '1.2' currency: EUR goods_description: Electronic components and accessories general_notes: 'Compliance: Goods comply with international safety standards (CE certified).' additional_declaration_statements: - With reference to the above shipment, I understate that the content is not made of leather parts of animal species protected by the Washington Convention. - I solemnly declare that the contents of this document represent a true and accurate account of the events as they occurred. I acknowledge my responsibility for the information presented herein and understand that any misrepresentation or falsification may result in legal consequences or other penalties as applicable. importer_of_record: name: John Doe company_name: ImporterCo address_line_1: Maple Avenue house_number: '123' postal_code: '90210' city: Springfield country_code: US state_province_code: US-MA telephone: '+15551234567' email: info@importer-of-record-example.com tax_numbers: sender: - name: VAT country_code: NL value: NL123456789B01 - name: EORI country_code: NL value: NL123456789 receiver: - name: EIN country_code: US value: '123456789' importer_of_record: - name: EIN country_code: US value: '987654321' properties: invoice_number: type: string minLength: 1 maxLength: 40 description: Customs invoice number. example: INV-123 export_reason: type: string description: Indicates the purpose or reason behind exporting the items. This classification helps customs authorities determine the applicable regulations, taxes, and duties. enum: - gift - documents - commercial_goods - commercial_sample example: commercial_goods export_type: type: string description: 'Export type documentation serves to categorize international shipments into three primary classifications: Private exports, intended for personal use; Commercial B2C exports, directed towards individual consumers; and Commercial B2B exports, involving business-to-business transactions. These distinctions facilitate adherence to regulatory requirements and ensure the orderly movement of goods across international boundaries.' enum: - private - commercial_b2c - commercial_b2b default: commercial_b2c example: private invoice_date: type: string format: date description: The date when the commercial invoice for the goods was issued (ISO 8601). If not provided, the announcement date will be used by default. discount_granted: 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 status: title: Status Object type: object description: Status object for a parcel properties: code: type: string example: ANNOUNCING message: type: string example: Being announced 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 optional-price: title: Optional price anyOf: - type: 'null' - $ref: '#/components/schemas/required-price' required-price: title: Price object description: Price, consisting of a value and currency. allOf: - $ref: '#/components/schemas/Price' - type: object required: - value - currency 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' address-validation-method-enum: title: Address validation method enum type: string enum: - here service-point-request: title: Service Point description: 'Node for service point information. Use the [Retrieve a list of service points](/api/v2/service-points/retrieve-a-list-of-service-points) endpoint to find service points, or pass in the carrier''s id for the service point. If both the `id` and `carrier_service_point_id` are provided, the `carrier_service_point_id` will be prioritised.' type: object anyOf: - title: Sendcloud ID type: object properties: id: type: string description: The sendcloud `id` of a service point. example: '123' required: - id - title: Carrier Service Point ID type: object properties: carrier_service_point_id: type: string description: The carrier's id of a service point example: '123' required: - carrier_service_point_id CustomsInformation: type: - object - 'null' title: Customs Information description: Customs information related to this shipment properties: discount_granted: type: - object - 'null' title: Discount Granted description: Discount granted on the total order $ref: '#/components/schemas/CostsObject' insurance_costs: type: - object - 'null' title: Insurance Cost description: Amount the order is insured for $ref: '#/components/schemas/CostsObject' freight_costs: type: - object - 'null' title: Freight Cost description: Shipping cost of the order $ref: '#/components/schemas/CostsObject' other_costs: type: - object - 'null' title: Other Costs description: Any other costs (for eg, wrapping costs) associated with the order $ref: '#/components/schemas/CostsObject' tax_numbers: type: - object - 'null' title: Tax information about sender, receiver, and importer of records properties: sender: type: array title: Sender's Tax Information minItems: 0 items: $ref: '#/components/schemas/TaxNumber_2' receiver: type: array title: Receiver's Tax Information minItems: 0 items: $ref: '#/components/schemas/TaxNumber_2' importer_of_records: type: array title: Receiver's Tax Information minItems: 0 items: $ref: '#/components/schemas/TaxNumber_2' 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 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 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 ShipmentBlobStatus: title: Shipment Blob Status Object type: - object - 'null' properties: id: title: Id type: string minLength: 1 description: Custom internal shop status, can be used for filtering message: title: Message type: string minLength: 1 description: User-defined human readable status required: - id - message 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' TaxNumber_2: type: object title: Tax Number properties: name: type: - string - 'null' title: Tax ID name example: VAT country_code: type: - string - 'null' title: The country code of the country in the address example: NL value: type: - string - 'null' title: The value of the Tax ID example: NL987654321B02 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 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 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 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. 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. \n\n**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 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: $ref: '#/components/schemas/parcel-item-with-optional-fields' minItems: 1 maxItems: 50 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 ParcelItems: title: Parcel Items Object type: object properties: description: type: string title: Description minLength: 1 description: Description of the type of product example: Bag hs_code: description: Harmonized System Code type: string title: HS code example: '01013000' maxLength: 12 origin_country: type: - string - 'null' title: Origin country enum: - AW - AF - AO - AI - AX - AL - AD - AE - AR - AM - AS - AQ - TF - AG - AU - AT - AZ - BI - BE - BJ - BQ - BF - BD - BG - BH - BS - BA - BL - BY - BZ - BM - BO - BR - BB - BN - BT - BV - BW - CF - CA - CC - CH - CL - CN - CI - CM - CD - CG - CK - CO - KM - CV - CR - CU - CW - CX - KY - CY - CZ - DE - DJ - DM - DK - DO - DZ - EC - EG - ER - EH - ES - EE - ET - FI - FJ - FK - FR - FO - FM - GA - GB - GE - GG - GH - GI - GN - GP - GM - GW - GQ - GR - GD - GL - GT - GF - GU - GY - HK - HM - HN - HR - HT - HU - ID - IM - IN - IO - IE - IR - IQ - IS - IL - IT - JM - JE - JO - JP - KZ - KE - KG - KH - KI - KN - KR - KW - LA - LB - LR - LY - LC - LI - LK - LS - LT - LU - LV - MO - MF - MA - MC - MD - MG - MV - MX - MH - MK - ML - MT - MM - ME - MN - MP - MZ - MR - MS - MQ - MU - MW - MY - YT - NA - NC - NE - NF - NG - NI - NU - NL - 'NO' - NP - NR - NZ - OM - PK - PA - PN - PE - PH - PW - PG - PL - PR - KP - PT - PY - PS - PF - QA - RE - RO - RU - RW - SA - SD - SN - SG - GS - SH - SJ - SB - SL - SV - SM - SO - PM - RS - SS - ST - SR - SK - SI - SE - SZ - SX - SC - SY - TC - TD - TG - TH - TJ - TK - TM - TL - TO - TT - TN - TR - TV - TW - TZ - UG - UA - UM - UY - US - UZ - VA - VC - VE - VG - VI - VN - VU - WF - WS - YE - ZA - ZM - ZW - IC - XK description: Country code from where the products were originally produced (ISO 3166-1 alpha-2) minLength: 2 maxLength: 2 product_id: type: string title: Product id description: Internal ID of the product example: '1458734634' properties: title: Properties type: object additionalProperties: type: - string - 'null' description: 'An object containing any additional properties of the product, e.g. `color: Black`' quantity: type: integer title: Quantity minimum: 1 description: Number of units of a given item example: 2 sku: type: string title: Sku description: Internal stock keeping unit, used by retailers to assign to products, in order to keep track of stock levels internally. example: WW-DR-GR-XS-001 value: title: Value type: string format: decimal description: Price of an item weight: title: Weight type: - string - 'null' format: decimal description: Weight of an item 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 required: - description - quantity - value 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.\n\nThere is a restriction to a maximum number of percels per shipment. \n\n* **sync** announcements : max 15 parcels per shipment\n* **async** announcements: max 50 parcels per shipment\n\nNote: 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 cancel-shipment-status: title: Cancel Shipment Status object type: object properties: data: $ref: '#/components/schemas/cancellation-status' required: - data 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 country-codes: type: string title: Country Code Object enum: - AW - AF - AO - AI - AX - AL - AD - AE - AR - AM - AS - AQ - TF - AG - AU - AT - AZ - BI - BE - BJ - BQ - BF - BD - BG - BH - BS - BA - BL - BY - BZ - BM - BO - BR - BB - BN - BT - BV - BW - CF - CA - CC - CH - CL - CN - CI - CM - CD - CG - CK - CO - KM - CV - CR - CU - CW - CX - KY - CY - CZ - DE - DJ - DM - DK - DO - DZ - EC - EG - ER - EH - ES - EE - ET - FI - FJ - FK - FR - FO - FM - GA - GB - GE - GG - GH - GI - GN - GP - GM - GW - GQ - GR - GD - GL - GT - GF - GU - GY - HK - HM - HN - HR - HT - HU - ID - IM - IN - IO - IE - IR - IQ - IS - IL - IT - JM - JE - JO - JP - KZ - KE - KG - KH - KI - KN - KR - KW - LA - LB - LR - LY - LC - LI - LK - LS - LT - LU - LV - MO - MF - MA - MC - MD - MG - MV - MX - MH - MK - ML - MT - MM - ME - MN - MP - MZ - MR - MS - MQ - MU - MW - MY - YT - NA - NC - NE - NF - NG - NI - NU - NL - 'NO' - NP - NR - NZ - OM - PK - PA - PN - PE - PH - PW - PG - PL - PR - KP - PT - PY - PS - PF - QA - RE - RO - RU - RW - SA - SD - SN - SG - GS - SH - SJ - SB - SL - SV - SM - SO - PM - RS - SS - ST - SR - SK - SI - SE - SZ - SX - SC - SY - TC - TD - TG - TH - TJ - TK - TM - TL - TO - TT - TN - TR - TV - TW - TZ - UG - UA - UM - UY - US - UZ - VA - VC - VE - VG - VI - VN - VU - WF - WS - YE - ZA - ZM - ZW - IC - XK description: A country represented by its ISO 3166-1 alpha-2 code example: NL 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\n * 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)\n * EIN - Employer Identification Number\n * GST - Goods and Service Tax\n * SSN - Social Security Number\n * EORI - Economic Operators Registration and Identification for the European Union\n * DUN - Data Universal Numbering System\n * FED - Federal Tax ID\n * STA - State Tax ID\n * CNP - Brazil CNPJ/CPF Federal Tax\n * IE - Brazil type IE/RG Federal Tax\n * INN - Russia bank details section INN\n * KPP - Russia bank details section KPP\n * OGR - Russia bank details section OGRN\n * OKP - Russia bank details section OKPO\n * 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\n * FTZ - Free Trade Zone ID\n * DAN - Deferment Account Duties Only\n * TAN - Deferment Account Tax Only\n * DTF - Deferment Account Duties, Taxes and Fees Only\n * RGP - EU Registered Exporters Registration ID\n * DLI - Driver's License\n * NID - National Identity Card - A PID (Personal Identification Number) should be provided as NID (National Identity Card).\n * PAS - Passport\n * MID - Manufacturer ID\n * 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)\n" 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 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 ErrorObject: title: Error type: object description: Error in a JSON:API error format properties: id: type: string description: A unique identifier for the error. links: type: object description: A set of hyperlinks that provide additional information about the error. properties: about: type: string description: A URL that provides additional information about the error. status: type: string format: int32 description: The HTTP status code of the error. minLength: 1 code: type: string description: A unique error code for the error, in snake case format. minLength: 1 enum: - unknown_field - invalid - forbidden - invalid_choice - min_value - 'null' - not_found - required - not_a_list - non_field_errors - authentication_failed - validation_error - parcel_announcement_error title: type: string description: A short, human-readable summary of the error. minLength: 1 detail: type: string description: A human-readable explanation of the error. minLength: 1 source: type: object description: An object that identifies the source of the error within the request payload. properties: pointer: type: string description: A `JSON` pointer to the location of the error within the request payload. parameter: type: string description: The name of the `query` parameter that caused the error. header: type: string description: The name of the `header` parameter that caused the error. meta: type: object description: Additional metadata about the error. shipment-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 address-washer-response: title: Address Washer Response description: Address Washer Response object model type: object properties: input_address_is_valid: type: boolean description: Indicates if the input address is valid. results: description: The results of the address validation. type: array items: type: object properties: address: $ref: '#/components/schemas/raw-address' recommended: type: boolean description: Indicates if the address is recommended after validation. analysis: type: object description: Analysis details of the address validation. 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 parcel-common: title: Parcel common Object description: Parcel common object model type: object allOf: - $ref: '#/components/schemas/parcel-common-with-optional-fields' - required: - weight - type: object properties: parcel_items: type: array description: List of items/products that the parcel contains. **Note that parcel items array is required for shipments that require customs documents.** maxItems: 1000 items: $ref: '#/components/schemas/parcel-item' CostsObject: properties: value: type: - string - 'null' pattern: '[\d]+(\.[\d]+)?' example: '3.99' currency: type: - string - 'null' example: EUR 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 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 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. ' items: $ref: '#/components/schemas/address-validation-method-enum' example: - here required: - to_address 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 dimension-units: type: string title: Dimensional units enum: - cm - mm - m - yd - ft - in example: mm CheckoutPayload: title: Checkout Payload Object type: object properties: sender_address_id: title: The [sender address unique identifier](../sender-addresses/openapi.yaml) associated with the order type: integer description: The sender_address_id associated with the order shipping_product: title: Shipping product type: object description: The shipping product with the associated functionalities of the order. See example payload. The `code`, `name` and `selected_functionalities` fields are **all required**. This data follows from the chosen `delivery_method` (by the end-consumer). delivery_method_type: title: Delivery method type type: string minLength: 1 description: The type of the delivery method. Needs to be either `standard_delivery`, `nominated_day_delivery` or `same_day_delivery`. delivery_method_data: type: object properties: delivery_date: title: Delivery date type: string format: date-time description: The delivery date required by the end-consumer formatted_delivery_date: type: string title: Formatted delivery date minLength: 1 example: February 21, 2012 parcel_handover_date: title: Parcel handover date type: string format: date-time description: Date at which the parcel needs to be handed over to the carrier required: - delivery_date - formatted_delivery_date - parcel_handover_date required: - sender_address_id - shipping_product - delivery_method_type ShipmentErrorLog: title: Shipment create/update error log type: object properties: error: title: Error(s) type: object external_order_id: title: External Order ID type: string external_shipment_id: title: External Shipment ID type: string status: title: Status type: string enum: - error 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 customs-information: title: CustomsInformation type: object allOf: - $ref: '#/components/schemas/customs-information-with-optional-fields' - required: - invoice_number - export_reason parcel-item-with-optional-fields: title: Parcel Item with optional fields Object description: A single item (with optional fields) in a shipment. **Note that parcel item object is required for shipments that require customs documents.** type: object properties: item_id: type: string description: Order Item external ID in shop system example: '5552' minLength: 1 description: type: string description: Description of the item example: T-Shirt XL minLength: 1 maxLength: 255 quantity: type: integer description: Quantity of items shipped minimum: 1 example: 1 weight: $ref: '#/components/schemas/weight' price: $ref: '#/components/schemas/required-price' hs_code: type: string description: Harmonized System Code. **This field is required if it's an international shipment** example: '620520' maxLength: 12 origin_country: type: string description: ISO-2 code of the country where the items were originally produced. **This field is required if it's an international shipment** example: NL sku: type: string description: The SKU of the product example: TS1234 product_id: type: string description: The internal ID of the product example: '19284' mid_code: title: MID Code type: - string - 'null' description: MID code is short for Manufacturer's Identification code and must be shown on the commercial invoice. It's used as an alternative to the full name and address of a manufacturer, shipper or exporter and is always required for U.S. formal customs entries. example: NLOZR92MEL material_content: title: Material Content type: - string - 'null' description: A description of materials of the order content. example: 100% Cotton intended_use: title: Intended Use type: - string - 'null' description: Intended use of the order contents. The intended use may be personal or commercial. example: Personal use dangerous_goods: $ref: '#/components/schemas/dangerous-goods' dds_reference: title: DDS Reference type: - string - 'null' description: The DDS (Due Diligence Statement) reference number associated with the item, if applicable. See EUDR system for more details. example: 25FIYPEK0A7573 taric_doc_code: title: TARIC document code type: - string - 'null' description: TARIC document codes are specific alphanumeric codes used in EU customs declarations (Box 44) to identify required supporting documents, certificates, or conditions for a product, like health certificates (e.g., 3200), origin proofs (e.g., EUR.1), or special authorizations (e.g., C716 for due diligence) for simplified procedures, ensuring compliance with EU trade rules for various goods. example: Y142 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 required: - quantity 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. ShipmentBlobOrder: title: Shipment Blob Order Object type: object properties: address: title: Address type: string minLength: 1 address_2: title: Address 2 type: string allowed_shipping_methods: type: array items: type: integer readOnly: true barcode: title: Barcode type: string minLength: 1 description: Barcode value of the label readOnly: true city: title: City type: string minLength: 1 company_name: title: Company name type: string country: $ref: '#/components/schemas/country-codes' created_at: type: string title: Created at format: date-time description: Timestamp indicating when the shipment was created in the Sendcloud system example: '2022-05-07T15:08:12.152000Z' currency: type: - string - 'null' title: Currency minLength: 1 description: ISO 4217 currency code enum: - EUR - USD - GBP customs_invoice_nr: type: string title: Customs invoice nr description: Your own commercial invoice number example: '120' customs_shipment_type: type: - integer - 'null' title: Customs shipment type enum: - 0 - 1 - 2 - 3 - 4 description: "Type of shipment for customs purposes:\n - `0` - Gift\n - `1` - Documents\n - `2` - Commercial Goods\n - `3` - Commercial Sample\n - `4` - Returned Goods\n" minimum: 0 maximum: 4 email: title: Customer email address type: string format: email external_order_id: title: External order id type: string minLength: 1 description: External order ID assigned by the shop system external_shipment_id: title: External shipment id type: - string - 'null' minLength: 1 description: External shipment ID assigned by the shop system house_number: title: House number type: string integration: title: Integration type: integer description: Sendcloud Integration ID readOnly: true name: title: Name type: string minLength: 1 order_number: title: Order number type: string minLength: 1 description: Unique order number generated manualy or by the shop system order_status: $ref: '#/components/schemas/ShipmentBlobStatus' parcel_items: type: - array - 'null' description: List of items the parcel contains items: $ref: '#/components/schemas/ParcelItems' payment_status: $ref: '#/components/schemas/ShipmentBlobStatus' postal_code: title: Postal code type: string minLength: 1 sender_address: title: Sender address type: - integer - 'null' description: ID of a sender address in the Sendcloud system readOnly: true shipment_uuid: type: string title: Shipment uuid minLength: 1 format: uuid description: Automatically generated Sendcloud's internal ID readOnly: true shipping_method: type: - integer - 'null' title: Shipping method description: Foreign key indicating shipping method used example: 1234 shipping_method_checkout_name: title: Shipping method checkout name type: string maxLength: 100 description: Human readable shipping method name telephone: title: Telephone type: string to_post_number: title: To post number type: string to_service_point: title: To service point type: - integer - 'null' to_state: title: To state type: - string - 'null' minLength: 1 total_order_value: title: Total order value type: - string - 'null' format: decimal description: The total price of an order updated_at: type: string title: Updated at format: date-time description: Timestamp for when the shipment was updated in the Sendcloud system example: '2022-05-07T15:08:12.152000Z' weight: type: - string - 'null' title: Weight format: decimal description: Total weight of the order. Cannot be smaler than 0.001 example: '10.2' maxLength: 10 checkout_payload: $ref: '#/components/schemas/CheckoutPayload' width: type: - string - 'null' title: Width description: Volumetric weight width format: decimal maxLength: 10 example: '10.2' height: type: - string - 'null' title: Height description: Volumetric weight height format: decimal maxLength: 10 example: '10.2' length: type: - string - 'null' title: Length description: Volumetric weight length format: decimal maxLength: 10 example: '10.2' customs_details: $ref: '#/components/schemas/CustomsInformation' shipment_created_at: type: string format: date-time description: Timestamp indicating when the shipment was created in the shop system example: '2022-07-07T15:08:12.152000Z' readOnly: true shipment_updated_at: type: string format: date-time description: Timestamp for when the shipment was updated in the shop system example: '2022-07-07T15:08:12.152000Z' readOnly: true required: - address - address_2 - city - company_name - country - created_at - currency - customs_invoice_nr - customs_shipment_type - email - external_order_id - external_shipment_id - house_number - name - order_number - order_status - parcel_items - payment_status - postal_code - shipping_method_checkout_name - telephone - to_post_number - to_service_point - to_state - updated_at - shipment_created_at - shipment_updated_at 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' type: object carrier: type: object description: Carrier used for the shipment. readOnly: true properties: code: type: string title: Carrier Code description: A carrier represented by a Sendcloud unique identifier. example: postnl name: type: string title: Carrier Name description: Carrier friendly name. example: PostNL 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.\n\n\n **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).**\n \n 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.\n \n 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.\n" 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 weight-units: type: string title: Mass Units Object enum: - kg - g - lbs - oz example: g 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.** 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.\n\nThere are 3 possible parameters to encode:\n- `o`: Offset\n- `r`: Reverse\n- `p`: Position\n \nFor 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 cursor-parameter: name: cursor in: query description: "The cursor query string will be used as the pivot value to filter results. If no value is provided, the service must return the first page. The value is Base64 encoded GET parameters. example:\n For a cursor string there are 3 possible parameters to encode:\n - o: Offset\n - r: Reverse\n - p: Position\n Combine into GET parameters. Example: r=1&p=300\n Base 64 encoded it would become: cj0xJnA9MzAw\n GET parameter in url would be https://some.url.com/api/endpoint/?cursor=cj0xJnA9MzAw\n" schema: type: string example: cj0xJnA9MzAw responses: 404-Shipments: description: Example response content: application/json: schema: type: object properties: error: type: object properties: code: type: integer description: HTTP response status code example: 404 request: type: string description: Endpoint which returned the response message: type: string description: Human readable error message required: - code - request - message examples: ShipmentNotFound: summary: Shipment not found value: error: code: 404 request: api/v2/integrations/1/shipments/ message: No ShipmentBlob matches the given query. IntegrationNotFound: summary: Integration not found value: error: code: 404 request: api/v2/integrations/1/shipments/ message: No Integration matches the given query. 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.