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
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:
            - write:parcel
      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: |-
          <Info>
            OAuth2 scopes required: `write:parcel`. See [Scopes for OAuth apps](/api/v3/scopes).
          </Info>

          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
                        parcel_ids:
                          - 420
                        shipment_id: '511'
                        order_id: 593c853e-ca90-4ab4-953c-fd2f47dd8dc3
                        order_number: ORD-2024-00174
                      - parcel_id: 4428
                        parcel_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
                        parcel_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
                        parcel_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
                        parcel_ids:
                          - 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
                        parcel_ids:
                          - 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:
            - write:parcel
      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: |-
          <Info>
            OAuth2 scopes required: `write:parcel`. See [Scopes for OAuth apps](/api/v3/scopes).
          </Info>

          <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
                  order:
                    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: array
                    description: Parcel ID, tracking details and generated label for each shipped order.
                    items:
                      $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:
  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.
    BadRequest:
      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:
                  - status: '400'
                    code: invalid
                    title: Invalid
                    detail: Input should be a valid string.
                    source:
                      pointer: /data/attributes/order/order_id
  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:
            read:analytics: View your shipping analytics
            read:audit-log: View your account's audit log
            read:brand: View your brands
            write:brand: Manage your brands
            write:carrier: Configure carriers and contracts
            read:checkout: View your dynamic checkout configurations and templates
            read:event-subscription: View your event subscriptions
            write:event-subscription: Create and manage your event subscriptions
            read:integration: View your integrations
            write:integration: Connect and manage integrations
            read:invoice: View your invoices
            read:notification: View your notifications
            write:notification: Manage your notifications
            read:operational-settings: View your warehouses, shipping lanes, and other operational settings
            write:operational-settings: Manage your warehouses, shipping lanes, and other operational settings
            read:order: View your orders
            write:order: Import and process your orders
            read:organization: View organization settings
            write:organization: Change organization settings
            read:parcel: View your shipments and their tracking status
            write:parcel: Create, announce, and cancel shipments
            read:pickup: View carrier pickups and the options available for scheduling them
            write:pickup: Schedule and manage carrier pickups
            read:price: View shipping prices
            write:product: Manage your product catalog
            read:return: View your returns
            write:return: Create and manage returns
            read:return-settings: View your return settings
            write:return-settings: Configure your return settings
            read:service-point: View carrier service points
            read:shipping-method: View shipping methods, products and prices
            read:shipping-rule: View your shipping rules
            write:shipping-rule: Create and manage shipping rules
            read:support-ticket: View your support tickets
            write:support-ticket: Manage your support tickets
            read:tracking-message: View your tracking notifications
            write:tracking-message: Manage your tracking notifications
            read:tracking-page: View your tracking page
            write:tracking-page: Customize your tracking page
            read:user: Read your basic account information
  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:
    shipping-option-code-properties:
      title: Shipping option properties Object
      description: Contains the required properties to be sent when API client informs the shipping method and carrier to be used
      type: object
      properties:
        shipping_option_code:
          type:
            - string
            - 'null'
          description: The shipping option that will be or is used for shipping your parcel. The code can be retrieved via the [Create a list of shipping options](/api/v3/shipping-options/create-a-list-of-shipping-options) endpoint. When `ship_with.type` is set to `shipping_option_code`, this field is mandatory.
          example: postnl:standard/insured=3000
        contract_id:
          type:
            - integer
            - 'null'
          minimum: 1
          description: The selected shipping contract. If you haven't specified a contract for shipping your parcel, we will automatically select the default contract for the carrier that matches your shipping option. You can retrieve your contract IDs from the [Retrieve a list of contracts](/api/v3/contracts/retrieve-a-list-of-contracts) endpoint. Otherwise, the default direct contract will be automatically selected.
    ship-with:
      title: Ship with object
      type: object
      description: |
        The ship with object can be used to define how you would like to send your shipment.

        You can use a `shipping_option_code`. This is a unique identifier that displays what carrier and what set of shipping functionalities you want to use.
      examples:
        - type: shipping_option_code
          properties:
            shipping_option_code: postnl:standard/insured=3000
            contract_id: 517
      properties:
        type:
          type: string
          description: |
            The way the shipping method and carrier will be selected. Nowadays the only possible value is 'shipping_option_code', which requires client to also send the `shipping_option_code` inside properties.
          enum:
            - shipping_option_code
          example: shipping_option_code
        properties:
          $ref: '#/components/schemas/shipping-option-code-properties'
      required:
        - type
        - properties
    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/v3/brands/retrieve-a-list-of-brands) endpoint.

            If not specified, the brand of the order's sender address is used. That's the sender address changed on the order, the sender address selected at checkout, the `sender_address_id` from your request, or your default sender address, in that order. If a shipping rule changes the sender address, the brand of that sender address is used, even if `brand_id` is specified. See [Brands](/docs/shipments/brands#how-the-brand-is-determined) for details.
          minimum: 1
        ship_with:
          type: object
          $ref: '#/components/schemas/ship-with'
      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
    dimension-units:
      type: string
      title: Dimensional units
      enum:
        - cm
        - mm
        - m
        - yd
        - ft
        - in
      example: mm
    str-dimensions:
      title: Dimensions
      type: object
      description: Dimensions in the specified unit
      properties:
        length:
          type: string
          description: length in specified unit
          example: '15'
        width:
          type: string
          description: width in specified unit
          example: '20.5'
        height:
          type: string
          description: height in specified unit
          example: '37'
        unit:
          $ref: '#/components/schemas/dimension-units'
      required:
        - length
        - width
        - height
        - unit
    weight-units:
      type: string
      title: Mass Units Object
      enum:
        - kg
        - g
        - lbs
        - oz
      example: g
    str-weight:
      title: Weight
      type: object
      description: Weight in the specified unit
      properties:
        value:
          type: string
          description: Weight value
          example: '14.5'
        unit:
          $ref: '#/components/schemas/weight-units'
      required:
        - value
        - unit
    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
    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
    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
    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-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'
    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 favor of the `parcel_ids` field, which returns an array containing the parcel ID (or multiple parcel IDs for a multicollo shipment).
              example: 420
              deprecated: true
            parcel_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-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: 203
                  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 valid DPI values per file format:

                    File format | Valid DPI
                    ----------- | -------------
                    pdf         | 72
                    png         | 150, 300
                    zpl         | 203, 300, 600

                    The default is `72`, which is only valid for PDF. When you request a PNG or ZPL label, you must also set `dpi` to a valid value for that format, otherwise the request fails.

                    For ZPL labels, the resolution of the label itself is determined by the carrier. 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:
      title: Documents Object
      type: object
      description: Documents object for a parcel
      properties:
        type:
          type: string
          deprecated: true
          description: |-
            The type of the document.

            **Deprecated** in favor of the `document_type` field, which groups these values into broader categories.
          enum:
            - label
            - cn23
            - cp71
            - commercial-invoice
            - cn23-default
            - air-waybill
            - qr
        document_type:
          type: string
          description: |-
            The type of the document. Use this value as the document type when you [retrieve a parcel document](/api/v3/parcel-documents/retrieve-a-parcel-document).

            - `label`: The shipping label. Replaces the `label` and `qr` values of the deprecated `type` field.
            - `customs-declaration`: The customs documents. Replaces the `cn23`, `cn23-default`, `cp71`, and `commercial-invoice` values of the deprecated `type` field.
            - `air-waybill`: The air waybill. Replaces the `air-waybill` value of the deprecated `type` field.
          enum:
            - label
            - customs-declaration
            - air-waybill
        size:
          type: string
          description: The paper size of the document.
          enum:
            - a6
            - a4
        link:
          type: string
          description: A link to the document, which allows downloading of the document in PDF, PNG and ZPL and various DPI.
    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:
              type: object
              description: The generated label file and its format.
              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: 203
                  description: The printing resolution of the returned label, as requested in `label_details.dpi`.
            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