Sendcloud Orders API v3

openapi: 3.1.0
info:
  title: Orders
  version: 3.0.0
  contact:
    name: Sendcloud API Support
    email: [email protected]
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
  description: >-
    The Orders API lets you manage your orders within Sendcloud. You can create
    and update orders in batch, retrieve a list of orders per integration,
    retrieve an order, partially update an order, and delete an order.
servers:
  - url: https://panel.sendcloud.sc/api/v3
    description: Sendcloud Production
tags:
  - name: Orders
    description: OrderAPI
paths:
  /orders:
    post:
      summary: Create/Update orders in batch
      description: Use this endpoint to insert orders into a Sendcloud API integration.
      x-mint:
        href: /api/v3/orders/create-update-orders-in-batch
        content: >-
          Each order can have a different integration id, so you can
          create/update orders for multiple integrations in one request.


          ## Upsert behavior


          This is an **upsert** endpoint, which means:

            - If an order with the same `order_id` and `integration.id` combination **already exists**, it will be **updated**
            - If no matching order exists, a **new order will be created**
            - **Optional**: You can include the Sendcloud `id` field to explicitly update a specific order
              - **Important**: When returned in responses, `id` is an **integer**, but when sending it in requests, it must be a **string**
              - Example: Response returns `"id": 669`, but request must send `"id": "669"`

          ## Batch processing


          - Process multiple orders in a single request (up to **100 orders
          maximum**)

          - Orders from different integrations can be included in the same batch

          - **All-or-nothing transaction**: If any order in the batch fails
          validation, the entire batch is rejected and zero orders are created
          or updated. There is no partial success — either all orders are
          processed or none are

          - On failure (HTTP 400), the response includes error details with
          `source.pointer` indicating which order in the array caused the issue
          (e.g., `[1]` for the second order, 0-indexed)

          - If you send multiple orders and one fails, you need to fix the
          failing order and resubmit the entire batch


          ## Limitations and constraints


          - **Maximum batch size**: 100 orders per request

          - **Upsert matching**: Orders are matched by the combination of
          `order_id` + `integration.id`

          - **Immutable fields**: When updating existing orders, certain fields
          like `order_id` cannot be changed

          - **Concurrent processing**: If the same `order_id` is being processed
          by another request, you'll receive a conflict error. Wait a moment and
          retry

          - **Integration access**: You can only create/update orders for
          integrations that belong to your account


          ## Asynchronous processing


          Order saving happens **asynchronously**. A successful `201` response
          means the request was accepted, but the order may not be immediately
          available for other operations (e.g., creating a label via the [Ship
          an Order API](/api/v3/ship-an-order)).


          - After creating an order, **verify it exists** by retrieving it with
          the [Retrieve an order](/api/v3/orders/retrieve-an-order) endpoint
          before attempting to ship it

          - If you plan to create an order and immediately ship it, allow a
          short delay and confirm the order is available before calling the Ship
          an Order API


          ## Best practices


          - Ensure all required fields are present before sending the request

          - Handle errors gracefully and implement retry logic for transient
          failures
      parameters:
        - $ref: '#/components/parameters/SendcloudPartnerId'
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                allOf:
                  - $ref: '#/components/schemas/order'
                  - type: object
                    properties:
                      id:
                        description: >-
                          Sendcloud's internal ID for the order.


                          - In **responses**: Returned as an integer (e.g.,
                          `669`)

                          - In **requests**: Optional field for explicitly
                          updating a specific order. Must be provided as a
                          string (e.g., `"669"`)

                          - If omitted in requests, the upsert logic uses the
                          combination of `order_id` + `integration.id` to match
                          existing orders
                        type: string
                        example: '669'
            examples:
              CreateBasicOrder:
                summary: Create a basic order with all required fields filled
                description: If you need create an order with only necessary info
                value:
                  - order_id: '555413'
                    order_number: OXSDFGHTD-12
                    order_details:
                      integration:
                        id: 7
                      status:
                        code: fulfilled
                        message: Fulfilled
                      order_created_at: '2018-02-27T10:00:00.556Z'
                      order_items:
                        - name: Cylinder candle
                          quantity: 1
                          total_price:
                            value: 3.5
                            currency: EUR
                    payment_details:
                      total_price:
                        value: 3.5
                        currency: EUR
                      status:
                        code: paid
                        message: Paid
                    shipping_address:
                      name: John Doe
                      address_line_1: Lansdown Glade
                      house_number: '15'
                      postal_code: 5341XT
                      city: Oss
                      country_code: NL
                    shipping_details:
                      is_local_pickup: false
                      delivery_indicator: DHL home delivery
                      measurement:
                        weight:
                          value: 3
                          unit: kg
              CreateInternationalOrder:
                summary: Create an international order with customs information
                description: >-
                  If an order going outside/inside EU it should contain
                  information needed for customs -- type of shipment and number
                  of commercial invoice
                value:
                  - order_id: '555413'
                    order_number: OXSDFGHTD-11
                    order_details:
                      integration:
                        id: 739283
                      status:
                        code: fulfilled
                        message: Order has been fulfilled
                      order_created_at: '2018-02-27T10:00:00.555Z'
                      order_updated_at: '2018-02-27T10:00:00.555Z'
                      order_items:
                        - name: Cylinder candle
                          description: Pebble green - 12x8 cm
                          hs_code: '010130'
                          country_of_origin: NL
                          measurement:
                            weight:
                              value: 1
                              unit: kg
                          quantity: 2
                          unit_price:
                            value: 3.5
                            currency: EUR
                          total_price:
                            value: 3.5
                            currency: EUR
                          mid_code: US1234567
                          material_content: 100% Cotton
                          intended_use: Personal use
                    payment_details:
                      total_price:
                        value: 7
                        currency: EUR
                      status:
                        code: paid
                        message: Order has been paid
                      discount_granted:
                        value: '3.99'
                        currency: EUR
                      insurance_costs:
                        value: '9.99'
                        currency: EUR
                      freight_costs:
                        value: '5.99'
                        currency: EUR
                      other_costs:
                        value: '2.99'
                        currency: EUR
                    customs_details:
                      commercial_invoice_number: 0124-03102022
                      shipment_type: commercial_goods
                      export_type: commercial_b2c
                      tax_numbers:
                        sender:
                          - name: VAT
                            country_code: NL
                            value: NL987654321B02
                        receiver:
                          - name: VAT
                            country_code: DE
                            value: DE123456789B03
                        importer_of_record:
                          - name: VAT
                            country_code: NL
                            value: NL975318642B01
                    shipping_address:
                      name: John Doe
                      address_line_1: Wilmington Drive
                      house_number: '15'
                      postal_code: '19804'
                      city: Dawnbrook
                      country_code: US
                      state_province_code: DE
                      phone_number: '+18882804331'
              CreateOrderProductImage:
                summary: Create an order that contains a product image URL
                description: >-
                  Allows you to send an order to Sendcloud containing a product
                  image URL which can then be used with returns, packing lists
                  and tracking
                value:
                  - order_id: '555413'
                    order_number: OXSDFGHTD-11
                    order_details:
                      integration:
                        id: 739283
                      status:
                        code: fulfilled
                        message: Order has been fulfilled
                      order_created_at: '2018-02-27T10:00:00.555Z'
                      order_updated_at: '2018-02-27T10:00:00.555Z'
                      order_items:
                        - name: Orange card
                          description: Orange gift card with face
                          hs_code: '010130'
                          country_of_origin: NL
                          measurement:
                            weight:
                              value: 1
                              unit: kg
                          quantity: 1
                          unit_price:
                            value: 3.5
                            currency: EUR
                          total_price:
                            value: 3.5
                            currency: EUR
                          image_url: https://i.ibb.co/6tLZ2Jz/orange.jpeg
                          product_id: '01544029'
                          variant_id: '458934950'
                    payment_details:
                      total_price:
                        value: 3.5
                        currency: EUR
                      status:
                        code: paid
                        message: Order has been paid
                    shipping_address:
                      name: John Doe
                      address_line_1: Vierlinghweg
                      house_number: '15'
                      postal_code: 2661TW
                      city: Breda
                      country_code: NL
                      state_province_code: NB
                      phone_number: '+31638426194'
                    shipping_details:
                      delivery_indicator: DHL home delivery
                      measurement:
                        weight:
                          value: 3
                          unit: kg
              CreateSpecifiedMeasurementsOrder:
                summary: Create an order with specified measurements
                description: >-
                  If you already know dimension or weight of orders, it could be
                  specified in `shipping_details` part
                value:
                  - order_id: '555413'
                    order_number: OXSDFGHTD-11
                    order_details:
                      integration:
                        id: 739283
                      status:
                        code: fulfilled
                        message: Order has been fulfilled
                      order_created_at: '2018-02-27T10:00:00.555Z'
                      order_updated_at: '2018-02-27T10:00:00.555Z'
                      order_items:
                        - name: Cylinder candle
                          description: Pebble green - 12x8 cm
                          measurement:
                            weight:
                              value: 1
                              unit: kg
                          quantity: 3
                          unit_price:
                            value: 3.5
                            currency: EUR
                          total_price:
                            value: 3.5
                            currency: EUR
                    payment_details:
                      total_price:
                        value: 10.5
                        currency: EUR
                      status:
                        code: paid
                        message: Order has been paid
                    shipping_address:
                      name: John Doe
                      address_line_1: Vierlinghweg
                      house_number: '15'
                      postal_code: 2661TW
                      city: Dordrecht
                      country_code: NL
                      state_province_code: NB
                      phone_number: '+31638426194'
                    shipping_details:
                      delivery_indicator: DHL home delivery
                      measurement:
                        dimension:
                          length: 0.15
                          width: 0.3
                          height: 0.3
                          unit: m
                        weight:
                          value: 3
                          unit: kg
                        volume:
                          value: 4
                          unit: l
              CreateSpecifiedBillingOrder:
                summary: Create an order with specified billing and customer info
                description: >-
                  If payer and recipient are different persons, you can specify
                  both in the `billing_address` and `customer_details` fields
                value:
                  - order_id: '555413'
                    order_number: OXSDFGHTD-12
                    order_details:
                      integration:
                        id: 739283
                      status:
                        code: fulfilled
                        message: Fulfilled
                      order_created_at: '2018-02-27T10:00:00.555Z'
                      order_updated_at: '2018-02-27T10:00:00.555Z'
                      order_items:
                        - name: Cylinder candle
                          description: Pebble green - 12x8 cm
                          measurement:
                            weight:
                              value: 1
                              unit: kg
                          quantity: 1
                          unit_price:
                            value: 3.5
                            currency: EUR
                          total_price:
                            value: 3.5
                            currency: EUR
                    payment_details:
                      total_price:
                        value: 3.5
                        currency: EUR
                      status:
                        code: paid
                        message: Paid
                    shipping_address:
                      name: John Doe
                      address_line_1: Tuindersweg
                      house_number: '15'
                      postal_code: 5341AW
                      city: Oss
                      country_code: NL
                    billing_address:
                      name: Jane Doe
                      address_line_1: Vioolstraat
                      house_number: '118'
                      postal_code: 5391TW
                      city: Breda
                      country_code: NL
                    customer_details:
                      name: Jane Doe
              CreateServicePointOrder:
                summary: >-
                  Create an order that will be delivered to a specific service
                  point
                description: >-
                  Instead of sending an order to the customers address you can
                  send the order to a service point for the customer to pick it
                  up from
                value:
                  - order_id: '555413'
                    order_number: OXSDFGHTD-12
                    order_details:
                      integration:
                        id: 739283
                      status:
                        code: fulfilled
                        message: Fulfilled
                      order_created_at: '2018-02-27T10:00:00.555Z'
                      order_updated_at: '2018-02-27T10:00:00.555Z'
                      order_items:
                        - name: Cylinder candle
                          description: Pebble green - 12x8 cm
                          measurement:
                            weight:
                              value: 1
                              unit: kg
                          quantity: 1
                          unit_price:
                            value: 3.5
                            currency: EUR
                          total_price:
                            value: 3.5
                            currency: EUR
                    payment_details:
                      total_price:
                        value: 3.5
                        currency: EUR
                      status:
                        code: paid
                        message: Paid
                    service_point_details:
                      id: '10875349'
                      extra_data:
                        partner_name: PostNL
                    shipping_address:
                      name: John Doe
                      address_line_1: Lansdown Glade
                      house_number: '15'
                      postal_code: 5341AB
                      city: Oss
                      country_code: NL
                      phone_number: '0612345678'
              CreateServicePointOrderByCarrierId:
                summary: Create an order using the carrier's native service point ID
                description: >-
                  You can use the carrier's native service point ID instead of
                  the Sendcloud service point ID to identify the service point
                value:
                  - order_id: '555414'
                    order_number: OXSDFGHTD-13
                    order_details:
                      integration:
                        id: 739283
                      status:
                        code: fulfilled
                        message: Fulfilled
                      order_created_at: '2018-02-27T10:00:00.555Z'
                      order_updated_at: '2018-02-27T10:00:00.555Z'
                      order_items:
                        - name: Cylinder candle
                          description: Pebble green - 12x8 cm
                          measurement:
                            weight:
                              value: 1
                              unit: kg
                          quantity: 1
                          unit_price:
                            value: 3.5
                            currency: EUR
                          total_price:
                            value: 3.5
                            currency: EUR
                    payment_details:
                      total_price:
                        value: 3.5
                        currency: EUR
                      status:
                        code: paid
                        message: Paid
                    service_point_details:
                      carrier_service_point_id: '91233'
                      extra_data:
                        partner_name: PostNL
                    shipping_address:
                      name: John Doe
                      address_line_1: Lansdown Glade
                      house_number: '15'
                      postal_code: 5341AB
                      city: Oss
                      country_code: NL
                      phone_number: '0612345678'
              UpdateBatchOrders:
                summary: Update orders in batch
                description: >-
                  If you want to update orders in batch, you can use this method
                  by specifying `id` in the request data
                value:
                  - id: '669'
                    order_id: '555413'
                    order_number: OXSDFGHTD-12
                    order_details:
                      integration:
                        id: 739283
                      status:
                        code: fulfilled
                        message: Fulfilled
                      order_created_at: '2018-02-27T10:00:00.555Z'
                      order_updated_at: '2018-02-28T11:05:15.634Z'
                      order_items:
                        - name: Cylinder candle
                          measurement:
                            weight:
                              value: 1.3
                              unit: kg
                          quantity: 1
                          unit_price:
                            value: 3.5
                            currency: EUR
                          total_price:
                            value: 3.5
                            currency: EUR
                    payment_details:
                      total_price:
                        value: 3.5
                        currency: EUR
                      status:
                        code: paid
                        message: Paid
                    shipping_address:
                      name: John Doe
                      address_line_1: Lansdown Glade
                      house_number: '15'
                      postal_code: 5341AB
                      city: Oss
                      country_code: NL
                      phone_number: '0612345678'
                  - id: '1337'
                    order_id: '555414'
                    order_number: OXSDFGHTD-13
                    order_details:
                      integration:
                        id: 739283
                      status:
                        code: fulfilled
                        message: Fulfilled
                      order_created_at: '2018-02-27T10:00:00.555Z'
                      order_updated_at: '2018-02-28T11:05:15.634Z'
                      order_items:
                        - name: Squared Candle
                          measurement:
                            weight:
                              value: 0.8
                              unit: kg
                          quantity: 3
                          unit_price:
                            value: 2
                            currency: EUR
                          total_price:
                            value: 6
                            currency: EUR
                        - name: Scented Candle
                          quantity: 2
                          unit_price:
                            value: 5.5
                            currency: EUR
                          total_price:
                            value: 11
                            currency: EUR
                    payment_details:
                      total_price:
                        value: 17
                        currency: EUR
                      status:
                        code: paid
                        message: Paid
                    shipping_address:
                      name: John Doe
                      address_line_1: Lansdown Glade
                      house_number: '15'
                      postal_code: 5341AB
                      city: Oss
                      country_code: NL
                      phone_number: '0612345678'
              CreateOrderShipWith:
                summary: Create a basic order with all required fields filled
                description: If you need create an order with only necessary info
                value:
                  - order_id: '555413'
                    order_number: OXSDFGHTD-12
                    order_details:
                      integration:
                        id: 7
                      status:
                        code: fulfilled
                        message: Fulfilled
                      order_created_at: '2018-02-27T10:00:00.556Z'
                      order_items:
                        - name: Cylinder candle
                          quantity: 1
                          total_price:
                            value: 3.5
                            currency: EUR
                    payment_details:
                      total_price:
                        value: 3.5
                        currency: EUR
                      status:
                        code: paid
                        message: Paid
                    shipping_address:
                      name: John Doe
                      address_line_1: Lansdown Glade
                      house_number: '15'
                      postal_code: 5341XT
                      city: Oss
                      country_code: NL
                    shipping_details:
                      is_local_pickup: false
                      delivery_indicator: DHL home delivery
                      measurement:
                        weight:
                          value: 3
                          unit: kg
                      ship_with:
                        type: shipping_option_code
                        properties:
                          shipping_option_code: postnl:standard
                          contract_id: 517
      responses:
        '201':
          description: OK.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      description: Create/Update orders in batch response object.
                      properties:
                        id:
                          description: Autogenerated Sendcloud's internal ID
                          type: integer
                          example: 234543
                        order_id:
                          type: string
                          description: External order ID assigned by shop system
                          example: 7bdd5bfd-76bc-4654-9d40-5d5d49f1cd6c
                        order_number:
                          type: string
                          description: >-
                            Unique order number generated manually or by shop
                            system
                          example: '101170081'
              examples:
                SingleOrderCreation:
                  description: >-
                    Response contains the identifiable information for the
                    customer to link the order in Sendcloud with the order in
                    the shop system
                  value:
                    data:
                      - id: 664
                        order_id: '555413'
                        order_number: OXSDFGHTD-12
                BatchOrderCreation:
                  description: >-
                    Response contains the identifiable information for the
                    customer to link the order in Sendcloud with the order in
                    the shop system
                  value:
                    data:
                      - id: 669
                        order_id: '555413'
                        order_number: OXSDFGHTD-12
                      - id: 1337
                        order_id: '555414'
                        order_number: OXSDFGHTD-13
        '400':
          description: >-
            Bad Request - Validation errors or business rule violations.


            **Error Response Structure**


            All errors use JSON Pointer notation in the `source.pointer` field
            to indicate the exact location of the problem:


            - `[N]` indicates which order in the batch array (0-indexed)

            - The path after shows the field hierarchy within that order

            - **Example**: `/data/attributes/[1]/order_details/integration`
            means the error is in the second order's integration field.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errors'
              examples:
                WrongPayloadFormatRequested:
                  summary: Wrong payload format
                  description: The request body is not in the expected array format
                  value:
                    errors:
                      - status: '400'
                        code: non_field_errors
                        title: Wrong format
                        detail: Wrong request format, expected list of objects
                MissingRequiredField:
                  summary: Missing required field
                  description: >-
                    An order in the batch is missing a required field. The array
                    index [1] indicates the second order in the batch
                    (0-indexed) has the error.
                  value:
                    errors:
                      - status: '400'
                        code: invalid
                        detail: Field required
                        source:
                          pointer: /data/attributes/[1]/order_details/integration
                MissingOrderId:
                  summary: Missing order ID
                  description: >-
                    An order in the batch is missing the required `order_id`
                    field.
                  value:
                    errors:
                      - status: '400'
                        code: invalid
                        detail: Field required
                        source:
                          pointer: /data/attributes/[0]/order_id
                InvalidFieldValue:
                  summary: Invalid field value
                  description: >-
                    An order has an invalid field value, such as a negative
                    quantity or invalid enum value.
                  value:
                    errors:
                      - status: '400'
                        code: invalid
                        detail: Input should be greater than 0
                        source:
                          pointer: >-
                            /data/attributes/[0]/order_details/order_items/0/quantity
                DuplicateOrderProcessing:
                  summary: Duplicate order being processed
                  description: >-
                    The batch contains an `order_id` that is currently being
                    processed by another request. This triggers a transaction
                    rollback - the entire batch is rejected and zero orders are
                    created. Wait a moment and retry the entire batch.
      

# --- truncated at 32 KB (113 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/sendcloud/refs/heads/main/openapi/sendcloud-v3-orders-openapi.yml