Sendcloud Orders API v3
Manage orders pulled in from connected commerce platforms and marketplaces. List, retrieve, update, and delete orders before converting them into shipments via the Ship an Order flow.
OpenAPI Specification
openapi: 3.1.0
info:
title: Orders
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 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