Sendcloud
Sendcloud Shipments API

Shipments API
Documentation GitHub OpenAPI
OpenAPI Specification

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
         

# --- truncated at 32 KB (283 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/sendcloud/refs/heads/main/openapi/sendcloud-shipments-api-openapi.yml
Sendcloud Shipments API

Documentation

Specifications

Schemas & Data

Other Resources

OpenAPI Specification
