Skip to main content
POST
/
orders
curl --request POST \
  --url https://panel.sendcloud.sc/api/v3/orders \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
[
  {
    "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"
        }
      }
    }
  }
]
'
{
  "data": [
    {
      "id": 664,
      "order_id": "555413",
      "order_number": "OXSDFGHTD-12"
    }
  ]
}
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).
  • After creating an order, verify it exists by retrieving it with the 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

Authorizations

​
Authorization
string
header
required

Basic Authentication using API key and secrets is currently the main authentication mechanism.

Headers

​
Sendcloud-Partner-Id
string

If you are an official Sendcloud Tech Partner, 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.

Body

application/json
​
order_id
string
required

External order ID assigned by shop system

Minimum string length: 1
Example:

"7bdd5bfd-76bc-4654-9d40-5d5d49f1cd6c"

​
order_number
string
required

Unique order number generated manually or by shop system

Minimum string length: 1
Example:

"101170081"

​
order_details
object
required

Node for general order information

​
payment_details
Payment Details · object
required

Node for everything about payments and money

​
customs_details
Customs Details · object

Customs information required for international shipments.

​
customer_details
Customer Details · object

Node for an information about customer

​
billing_address
Billing Address · object

Sendcloud Billing Address object

​
shipping_address
Shipping Address · object

Sendcloud Shipping Address object

​
shipping_details
object

Shipping information

​
service_point_details
Sendcloud ID · object

Node for service point information. The service point information can be retrieved from the Service points API.

You must provide either the Sendcloud id or the carrier_service_point_id to identify the service point.

​
id
string

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
Example:

"669"

Response

OK.

​
data
object[]