> ## Documentation Index
> Fetch the complete documentation index at: https://sendcloud.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Request a label for one or more orders asynchronously

> 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.

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>


## OpenAPI

````yaml /.openapi/v3/ship-an-order/openapi.yaml post /orders/create-labels-async
openapi: 3.1.0
info:
  title: Ship an Order
  version: 3.0.0
  contact:
    name: Sendcloud API Support
    email: contact@sendcloud.com
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
  description: |
    The Sendcloud Ship an Order API

    ## What can you do with this API?

    - [Create Labels for orders](/docs/orders/ship-an-order/).
servers:
  - url: https://panel.sendcloud.sc/api/v3
    description: Sendcloud Production
security: []
tags:
  - name: Ship an Order
    description: OrderLabelAPI
paths:
  /orders/create-labels-async:
    post:
      tags:
        - Ship an Order
      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.
      operationId: sc-public-v3-orders_labels-post-create_labels_async
      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'
      security:
        - HTTPBasicAuth: []
        - OAuth2ClientCreds: []
components:
  parameters:
    SendcloudPartnerId:
      in: header
      name: Sendcloud-Partner-Id
      description: >-
        If you are an official [Sendcloud Tech
        Partner](https://www.sendcloud.com/ecosystem/), send your unique
        Sendcloud Partner UUID as a request header for the system to recognize
        you.


        The header is not required but if it is set, the system will check it.
        An unknown or invalid UUID will cause a 400 error.
      schema:
        type: string
  schemas:
    create-labels-async:
      title: Create labels asynchronously
      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:
            - orders
            - integration_id
          properties:
            orders:
              type: array
              minItems: 1
              maxItems: 20
              uniqueItems: true
              description: Array of order objects you want to create labels for
              items:
                allOf:
                  - $ref: '#/components/schemas/create-labels-parcels'
                  - oneOf:
                      - $ref: '#/components/schemas/OrderSelectorOrderIdRequired'
                      - $ref: '#/components/schemas/OrderSelectorOrderNumberRequired'
    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
    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.
    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
    create-labels-base:
      type: object
      required:
        - integration_id
      properties:
        integration_id:
          type: integer
          description: The ID of the integration your orders belong to.
          example: 70
        sender_address_id:
          type: integer
          example: 192
          description: >-
            The ID of the sender address you would like to ship from. If not
            specified, your default sender address will be used.


            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.
        brand_id:
          type: integer
          example: 42
          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 using the [Retrieve a list of
            brands](/api/v2/brands/retrieve-a-list-of-brands) endpoint.


            > **Note:** The Brands API is currently only available in API v2.
            This reference will be updated when a v3 version becomes available.
          minimum: 1
        ship_with:
          $ref: '#/components/schemas/ship-with'
          type: object
      components:
        schemas:
          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:
                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 for this order.
                default: false
                example: false
            required:
              - order_id
          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
    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
    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:
          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 for this order.
          default: false
          example: false
      required:
        - order_id
    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
    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:
          $ref: '#/components/schemas/ship-with'
          type: object
    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
    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
    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 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'
    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
    str-dimensions:
      title: Dimensions
      type: object
      description: Dimensions in the specified unit
      properties:
        length:
          type: string
          description: length in specified unit
          example: '15'
        width:
          type: string
          description: width in specified unit
          example: '20.5'
        height:
          type: string
          description: height in specified unit
          example: '37'
        unit:
          $ref: '#/components/schemas/dimension-units'
      required:
        - length
        - width
        - height
        - unit
    str-weight:
      title: Weight
      type: object
      description: Weight in the specified unit
      properties:
        value:
          type: string
          description: Weight value
          example: '14.5'
        unit:
          $ref: '#/components/schemas/weight-units'
      required:
        - value
        - unit
    dimension-units:
      type: string
      title: Dimensional units
      enum:
        - cm
        - mm
        - m
        - yd
        - ft
        - in
      example: mm
    weight-units:
      type: string
      title: Mass Units Object
      enum:
        - kg
        - g
        - lbs
        - oz
      example: g
  responses:
    NotFound:
      description: Not Found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errors'
          examples:
            PageNotFound:
              summary: The page you have requested could not be found.
              value:
                errors:
                  - status: '404'
                    code: not_found
                    title: Not found
                    detail: The page you have requested could not be found.
  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.

````