Sendcloud Ship an Order API

openapi: 3.1.0
info:
  title: Shipments Address Ship an Order 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: Ship an Order
  description: OrderLabelAPI
paths:
  /orders/create-labels-async:
    post:
      tags:
      - Ship an Order
      operationId: sc-public-v3-orders_labels-post-create_labels_async
      security:
      - HTTPBasicAuth: []
      - OAuth2ClientCreds: []
      summary: Request a label for one or more orders asynchronously
      description: Request a label for a single or multiple orders. This endpoint will fail gracefully if some orders cannot be processed, returning any successfully created labels along with error details for the orders that failed.
      x-mint:
        href: /api/v3/ship-an-order/request-a-label-for-one-or-more-orders-asynchronously
        content: 'To retrieve your documents or view announcement errors, use the `id` of the relevant shipment with the [Retrieve a shipment](/api/v3/shipments/retrieve-a-shipment) endpoint.


          To apply shipping rules to the orders, make sure to set `apply_shipping_rules` to `true`.


          This endpoint will attempt to generate labels for each order. If a request for one label errors, it will still attempt to generate the other labels. Because of this, the response might return a mix of labels and errors. Use the errors `source` `pointer` field to see which labels encountered a problem.


          <Note>

          If you create orders via the [Orders API](/api/v3/orders/create-update-orders-in-batch) and then immediately request labels, the orders may not yet be available. Order saving is **asynchronous**. A successful `201` response from the Orders API does not guarantee the order is immediately ready for shipping. Before calling this endpoint, verify the order exists by retrieving it with the [Retrieve an order](/api/v3/orders/retrieve-an-order) endpoint.

          </Note>'
      parameters:
      - $ref: '#/components/parameters/SendcloudPartnerId'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/create-labels-async'
            examples:
              CreateSingleLabelAsync:
                summary: Create a label for a specific order.
                description: Create a single shipping label for the order you want to ship.
                value:
                  integration_id: 70
                  orders:
                  - order_number: ORDER-25763
                    apply_shipping_rules: false
              CreateLabelUsingSenderAddressIDAsync:
                summary: Create a label for a specific order using a sender address ID.
                description: Create a single shipping label where the sender address is being supplied through ID.
                value:
                  integration_id: 70
                  sender_address_id: 17
                  orders:
                  - order_number: ORDER-25763
              CreateLabelUsingBrandIDAsync:
                summary: Create a label for a specific order using a brand ID.
                description: Create a single shipping label where the brand is being set through ID.
                value:
                  integration_id: 70
                  brand_id: 42
                  orders:
                  - order_number: ORDER-25763
              CreateLabelUsingShipWithAsync:
                summary: Create a label for a specific order using a specific shipping option.
                description: Create a single shipping label where the carrier and the shipping functionalities are defined by the supplied shipping_option_code.
                value:
                  integration_id: 70
                  ship_with:
                    type: shipping_option_code
                    properties:
                      contract_id: 517
                      shipping_option_code: postnl:standard
                  orders:
                  - order_number: ORDER-25763
              CreateLabelsAsync:
                summary: Create a label for a multiple orders.
                description: Create shipping labels for orders you want to sent to your customers.
                value:
                  integration_id: 70
                  orders:
                  - order_number: ORDER-257633
                    apply_shipping_rules: false
                  - order_id: d59e8b1c-04ca-4b38-90cf-e11083506e22
              CreateMulticolloLabelAsync:
                summary: Create multiple labels for an order.
                description: Create shipping labels for order you want to sent in multiple parcels.
                value:
                  integration_id: 70
                  orders:
                  - order_number: ORDER-25763
                    parcels:
                    - parcel_items:
                      - item_id: '5552'
                        quantity: 1
                      - item_id: '5555'
                        quantity: 2
                      dimensions:
                        length: '5.00'
                        width: '15.00'
                        height: '20.00'
                        unit: cm
                      weight:
                        value: '1.320'
                        unit: kg
                    - parcel_items:
                      - item_id: '5552'
                        quantity: 1
                      - item_id: '763'
                        quantity: 12
                      dimensions:
                        length: '10.00'
                        width: '12.00'
                        height: '30.00'
                        unit: cm
                      weight:
                        value: '2.2'
                        unit: kg
                    apply_shipping_rules: false
      responses:
        '202':
          description: Information about the created parcels.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    description: An array containing the created parcel IDs and other order information.
                    minItems: 0
                    items:
                      $ref: '#/components/schemas/label-async'
                  errors:
                    type:
                    - array
                    items:
                      type: object
                      allOf:
                      - $ref: '#/components/schemas/ErrorObject'
                      required:
                      - status
                      - code
                      - detail
              examples:
                AllLabelsSuccessful:
                  description: All the requested labels were successfully generated.
                  value:
                    data:
                    - parcel_id: 420
                      parcels_ids:
                      - 420
                      shipment_id: '511'
                      order_id: 593c853e-ca90-4ab4-953c-fd2f47dd8dc3
                      order_number: ORD-2024-00174
                    - parcel_id: 4428
                      parcels_ids:
                      - 4428
                      shipment_id: '512'
                      order_id: '23458265234'
                      order_number: ORD-2024-00166
                MulticolloLabelsSuccessful:
                  description: A single order shipped in multiple parcels.
                  value:
                    data:
                    - parcel_id: 420
                      parcels_ids:
                      - 420
                      - 421
                      - 422
                      shipment_id: '511'
                      order_id: 593c853e-ca90-4ab4-953c-fd2f47dd8dc3
                      order_number: ORD-2024-00174
                SomeLabelsContainErrors:
                  description: Some labels were generated, while others encountered an error.
                  value:
                    data:
                    - parcel_id: 420
                      parcels_ids:
                      - 420
                      shipment_id: '511'
                      order_id: 593c853e-ca90-4ab4-953c-fd2f47dd8dc3
                      order_number: ORD-2024-00174
                    errors:
                    - status: '400'
                      code: validation_error
                      title: Invalid order
                      detail: The order has no valid shipping address.
                      source:
                        pointer: /data/attributes/orders/[1]
                SenderAddressIDDoesNotExist:
                  description: Sender Address does not exist.
                  value:
                    errors:
                    - status: '404'
                      code: invalid
                      detail: Does not exist.
                      source:
                        pointer: /data/attributes/sender_address_id
                LabelsSuccessfulWithShipWith:
                  description: All the requested labels were successfully generated using the provided `ship_with` option.
                  value:
                    data:
                    - parcel_id: 420
                      shipment_id: '511'
                      order_id: 593c853e-ca90-4ab4-953c-fd2f47dd8dc3
                      order_number: ORD-2024-00174
                      ship_with:
                        type: shipping_option_code
                        properties:
                          contract_id: 517
                          shipping_option_code: postnl:standard
                    - parcel_id: 4428
                      shipment_id: '512'
                      order_id: '23458265234'
                      order_number: ORD-2024-00166
                      ship_with:
                        type: shipping_option_code
                        properties:
                          contract_id: 517
                          shipping_option_code: postnl:standard
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errors'
              examples:
                InvalidOrderId:
                  summary: The provided order_id is not a valid string.
                  value:
                    errors:
                    - detail: Input should be a valid string
                      status: '400'
                      source:
                        pointer: /data/attributes/orders/0/order_id
                      code: invalid
        '404':
          $ref: '#/components/responses/NotFound'
  /orders/create-label-sync:
    post:
      tags:
      - Ship an Order
      operationId: sc-public-v3-orders_labels-post-create_labels_sync
      security:
      - HTTPBasicAuth: []
      - OAuth2ClientCreds: []
      summary: Request a label for a single order synchronously
      description: Request a label for a single order and wait for the results. The label and any other documents will be provided in the response to this request.
      x-mint:
        href: /api/v3/ship-an-order/request-a-label-for-a-single-order-synchronously
        content: '<Note>

          If you create orders via the [Orders API](/api/v3/orders/create-update-orders-in-batch) and then immediately request a label, the order may not yet be available. Order saving is **asynchronous**. A successful `201` response from the Orders API does not guarantee the order is immediately ready for shipping. Before calling this endpoint, verify the order exists by retrieving it with the [Retrieve an order](/api/v3/orders/retrieve-an-order) endpoint.

          </Note>'
      parameters:
      - $ref: '#/components/parameters/SendcloudPartnerId'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/create-labels-sync'
            examples:
              CreateSingleLabelSync:
                summary: Create a label for a specific order.
                description: Create a shipping label for the order you want to ship.
                value:
                  integration_id: 70
                  label_details:
                    mime_type: application/pdf
                    dpi: 72
                  order:
                    order_number: ORDER-25763
                    apply_shipping_rules: false
              CreateLabelUsingShipWithSync:
                summary: Create a label for a specific order using a specific shipping option.
                description: Create a single shipping label where the carrier and the shipping functionalities are defined by the supplied `shipping_option_code`.
                value:
                  integration_id: 70
                  ship_with:
                    type: shipping_option_code
                    properties:
                      contract_id: 517
                      shipping_option_code: postnl:standard
                  order:
                  - order_number: ORDER-25763
              CreateLabelUsingSenderAddressIDSync:
                summary: Create a label for a specific order using a sender address ID.
                description: Create a shipping label using a specific sender address.
                value:
                  integration_id: 70
                  sender_address_id: 17
                  label_details:
                    mime_type: application/pdf
                    dpi: 72
                  orders:
                  - order_number: ORDER-25763
              CreateLabelUsingBrandIDSync:
                summary: Create a label for a specific order using a brand ID.
                description: Create a single shipping label using a specific brand.
                value:
                  integration_id: 70
                  brand_id: 42
                  label_details:
                    mime_type: application/pdf
                    dpi: 72
                  order:
                    order_number: ORDER-25763
      responses:
        '201':
          description: Parcel ID along with generated label.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    description: Parcel ID, tracking details and generated label.
                    $ref: '#/components/schemas/label-sync'
              examples:
                LabelSuccessfulWithShipWith:
                  description: All requested labels are being generated with the provided `ship_with`.
                  value:
                    data:
                    - parcel_id: 420
                      shipment_id: '511'
                      order_id: 593c853e-ca90-4ab4-953c-fd2f47dd8dc3
                      order_number: ORD-2024-00174
                      ship_with:
                        type: shipping_option_code
                        properties:
                          contract_id: 517
                          shipping_option_code: postnl:standard
                      tracking_number: ABCD1234567890
                      tracking_url: https://test.shipping-portal.com/tracking/?tracking_number=abcd1234567890&country=nl&postal_code=1234AB
                      label:
                        file: <base64-encoded-pdf-data>
                        mime_type: application/pdf
                        dpi: 72
                      documents:
                      - type: label
                        size: a6
                        link: https://panel.sendcloud.sc/api/v3/parcels/1234567890/documents/label
                    - parcel_id: 4428
                      shipment_id: '512'
                      order_id: '23458265234'
                      order_number: ORD-2024-00166
                      ship_with:
                        type: shipping_option_code
                        properties:
                          contract_id: 517
                          shipping_option_code: postnl:standard
                      tracking_number: ABCD1234567890
                      tracking_url: https://test.shipping-portal.com/tracking/?tracking_number=abcd1234567890&country=nl&postal_code=1234AB
                      label:
                        file: <base64-encoded-pdf-data>
                        mime_type: application/pdf
                        dpi: 72
                      documents:
                      - type: label
                        size: a6
                        link: https://panel.sendcloud.sc/api/v3/parcels/1234567890/documents/label
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  parameters:
    SendcloudPartnerId:
      in: header
      name: Sendcloud-Partner-Id
      description: 'If you are an official [Sendcloud Tech Partner](https://www.sendcloud.com/ecosystem/), send your unique Sendcloud Partner UUID as a request header for the system to recognize you.


        The header is not required but if it is set, the system will check it. An unknown or invalid UUID will cause a 400 error.'
      schema:
        type: string
  schemas:
    label-base:
      type: object
      properties:
        shipment_id:
          type: string
          description: The ID of the shipment that was created for the provided order.
          example: '511'
        order_id:
          type: string
          description: The ID of your order.
          example: 593c853e-ca90-4ab4-953c-fd2f47dd8dc3
        order_number:
          type: string
          description: A human-readable order number.
          example: ORD-2024-01414
        ship_with:
          type: object
          $ref: '#/components/schemas/ship-with'
    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
    errors:
      title: Errors
      type: object
      description: A standardized format for errors in JSON:API responses.
      properties:
        errors:
          type:
          - array
          - object
          items:
            type: object
            allOf:
            - $ref: '#/components/schemas/ErrorObject'
            required:
            - status
            - code
            - detail
    label-sync:
      title: Reference to label
      type: object
      description: Holds the reference to created label.
      allOf:
      - $ref: '#/components/schemas/label-base'
      - type: object
        properties:
          parcel_id:
            type: integer
            description: The ID of the parcel the label belongs to.
            example: 420
          label_details:
            type: object
            properties:
              file:
                type: string
                format: byte
                description: The base64 representation of the label file.
              mime_type:
                type: string
                default: application/pdf
                enum:
                - application/pdf
                - application/zpl
                - image/png
                example: application/zpl
                description: The returned format of the label.
              dpi:
                type: integer
                default: 72
                enum:
                - 72
                - 150
                - 203
                - 300
                - 600
                example: 72
                description: 'DPI refers to the printing resolution of your shipping labels. It''s important that labels are printed at a high enough resolution to ensure the clarity of address details and the barcode for scanning purposes.


                  Refer to the following table for DPI settings per file format:


                  File format | Default DPI | Valid DPI

                  ----------- | ----------- | ---------

                  pdf         | 72          | 72

                  png         | 300         | 150, 300


                  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.'
          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
          tracking_url:
            type: string
            description: Tracking url of this shipment.
            readOnly: true
    label-async:
      title: Reference to label
      type: object
      description: Holds the reference to created label.
      allOf:
      - $ref: '#/components/schemas/label-base'
      - type: object
        properties:
          parcel_id:
            type: integer
            description: 'The ID of the parcel the label belongs to. For multicollo shipments, the ID of the first parcel will be returned.


              **Deprecated** in favour of the `parcels_ids` field, which returns an array containing the parcel ID (or multiple parcel IDs for a multicollo shipment).'
            example: 420
            deprecated: true
          parcels_ids:
            type: array
            description: An array containing the IDs of all the parcels the labels belong to.
            example:
            - 420
            items:
              type: integer
              example: 420
    create-labels-sync:
      title: Create labels synchronously
      description: 'Payload for creating labels for orders.


        Note that if the `sender_address_id` is not specified, the API will use the default [sender address](/docs/getting-started/sender-addresses) associated with your account.

        '
      type: object
      allOf:
      - $ref: '#/components/schemas/create-labels-base'
      - type: object
        required:
        - order
        - integration_id
        properties:
          order:
            type: object
            oneOf:
            - $ref: '#/components/schemas/OrderSelectorOrderIdRequired'
            - $ref: '#/components/schemas/OrderSelectorOrderNumberRequired'
          label_details:
            type: object
            properties:
              mime_type:
                type: string
                default: application/pdf
                enum:
                - application/pdf
                - application/zpl
                - image/png
                example: application/zpl
                description: The returned format of the label.
              dpi:
                type: integer
                default: 72
                enum:
                - 72
                - 150
                - 203
                - 300
                - 600
                example: 72
                description: 'DPI refers to the printing resolution of your shipping labels. It''s important that labels are printed at a high enough resolution to ensure the clarity of address details and the barcode for scanning purposes.


                  Refer to the following table for DPI settings per file format:


                  File format | Default DPI | Valid DPI

                  ----------- | ----------- | ---------

                  pdf         | 72          | 72

                  png         | 300         | 150, 300


                  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.'
    CreateLabelParcel:
      type: object
      allOf:
      - $ref: '#/components/schemas/parcel-common-with-optional-fields'
      - type: object
        properties:
          parcel_items:
            type: array
            description: List of items/products from the order that the parcel contains.
            maxItems: 1000
            items:
              $ref: '#/components/schemas/OrderItem'
      required:
      - parcel_items
    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
    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.
    OrderItem:
      type: object
      properties:
        item_id:
          type: string
          description: The order item's external ID in the shop system. This `item_id` can be obtained via the [Retrieve an order](/api/v3/orders/retrieve-an-order) endpoint.
          example: '5552'
          minLength: 1
        quantity:
          type: integer
          description: Quantity of items shipped.
          minimum: 1
          example: 1
      required:
      - item_id
      - quantity
    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 generally optional, some carriers require them to be present. If this is the case, an error will be thrown.
        weight:
          $ref: '#/components/schemas/str-weight'
    create-labels-parcels:
      title: Multicollo parcels array Object
      description: Multicollo parcels array model used for splitting shipped object into multiple parcels
      type: object
      properties:
        parcels:
          description: Represents each package in the shipment. Each carrier can have its own limit for the number of parcels per shipment, otherwise there is a default maximum of 50 parcels. If left empty, one parcel will be created from an entire order.
          type: array
          items:
            $ref: '#/components/schemas/CreateLabelParcel'
          minItems: 1
          maxItems: 50
      components:
        schemas:
          OrderItem:
            type: object
            properties:
              item_id:
                type: string
                description: The order item's external ID in the shop system. This `item_id` can be obtained via the [Retrieve an order](/api/v3/orders/retrieve-an-order) endpoint.
                example: '5552'
                minLength: 1
              quantity:
                type: integer
                description: Quantity of items shipped.
                minimum: 1
                example: 1
            required:
            - item_id
            - quantity
          CreateLabelParcel:
            type: object
            allOf:
            - $ref: '#/components/schemas/parcel-common-with-optional-fields'
            - type: object
              properties:
                parcel_items:
                  type: array
                  description: List of items/products from the order that the parcel contains.
                  maxItems: 1000
                  items:
                    $ref: '#/components/schemas/OrderItem'
            required:
            - parcel_items
    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.
    OrderSelectorOrderNumberRequired:
      type: object
      properties:
        order_id:
          type: string
          minLength: 1
          maxLength: 64
          description: External order ID assigned by shop system. Used to identify an order to be shipped.
        order_number:
          type: string
          minLength: 1
          maxLength: 255
          description: An identification of an order in a shop system (often unique). Used to identify an order to be shipped.
        apply_shipping_rules:
          type: boolean
          description: Apply shipping rules to this order.
          default: false
          example: false
      required:
      - order_number
    OrderSelectorOrderIdRequired:
      type: object
      properties:
        order_id:
          type: string
          minLength: 1
          maxLength: 64
          description: An external order ID assigned by the shop system. Used to identify an order to be shipped.
        order_number:
    

# --- truncated at 32 KB (40 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/sendcloud/refs/heads/main/openapi/sendcloud-ship-an-order-api-openapi.yml