Sendcloud Orders API

openapi: 3.1.0
info:
  title: Shipments Address Orders API
  version: 3.0.0
  description: The Shipments API allows you to create and announce, retrieve, and cancel outgoing shipments and their associated parcels within the Sendcloud platform.
  contact:
    name: Sendcloud API Support
    email: contact@sendcloud.com
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
servers:
- url: https://panel.sendcloud.sc/api/v3
  description: Sendcloud Production
tags:
- name: 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.\n\n## Upsert behavior\n\nThis is an **upsert** endpoint, which means:\n\n  - If an order with the same `order_id` and `integration.id` combination **already exists**, it will be **updated**\n  - If no matching order exists, a **new order will be created**\n  - **Optional**: You can include the Sendcloud `id` field to explicitly update a specific order\n    - **Important**: When returned in responses, `id` is an **integer**, but when sending it in requests, it must be a **string**\n    - Example: Response returns `\"id\": 669`, but request must send `\"id\": \"669\"`\n\n## Batch processing\n\n- Process multiple orders in a single request (up to **100 orders maximum**)\n- Orders from different integrations can be included in the same batch\n- **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\n- 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)\n- If you send multiple orders and one fails, you need to fix the failing order and resubmit the entire batch\n\n## Limitations and constraints\n\n- **Maximum batch size**: 100 orders per request\n- **Upsert matching**: Orders are matched by the combination of `order_id` + `integration.id`\n- **Immutable fields**: When updating existing orders, certain fields like `order_id` cannot be changed\n- **Concurrent processing**: If the same `order_id` is being processed by another request, you'll receive a conflict error. Wait a moment and retry\n- **Integration access**: You can only create/update orders for integrations that belong to your account\n\n## Asynchronous processing\n\nOrder 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)).\n\n- 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\n- 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\n\n## Best practices\n\n- Ensure all required fields are present before sending the request\n- 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.
                  value:
                    errors:
                    - status: '400'
                      code: invalid
                      detail: We are still processing a previous request. Please try again in a moment.
                      source:
                        pointer: /data
                BatchSizeLimitExceeded:
                  summary: Batch size limit exceeded
                  description: The request contains more than 100 orders. The maximum batch size is 100 orders per request.
                  value:
                    errors:
                    - status: '400'
                      code: invalid
                      detail: Orders list should have at most 100 items, not 101
                      source:
                        pointer: /data/attributes/
                MultipleValidationErrors:
                  summary: Multiple validation errors
                  description: Multiple fields have validation errors. All errors are returned together to help fix all issues at once.
                  value:
                    errors:
                    - status: '400'
                      code: invalid
                      detail: Field required
                      source:
                        pointer: /data/attributes/[0]/shipping_details/ship_with/properties
                    - status: '400'
                      code: invalid
                      detail: Field required
                      source:
                        pointer: /data/attributes/[0]/shipping_details/ship_with/type
                IntegrationNotFound:
                  summary: Integration not found
                  description: The specified integration ID does not exist or does not belong to your account.
                  value:
                    errors:
                    - status: '400'
                      code: invalid
                      detail: Integration with id 99999 does not exist
                      source:
                        pointer: /data/attributes/[0]/order_details/integration/id
                ImmutableFieldChange:
                  summary: Immutable field change attempted
                  description: When updating an existing order (upsert), certain fields like `order_id` cannot be changed. This error occurs when trying to modify an immutable field.
                  value:
                    errors:
                    - status: '400'
                      code: invalid
                      detail: Order id abc-123 cannot be changed
                      source:
                        pointer: /data/attributes/[0]/order_id
                InvalidIdType:
                  summary: Invalid id field type
                  description: 'The Sendcloud `id` field has a type mismatch between requests and responses.


                    - In *

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