Skip to main content
You can use the Orders API to create, retrieve, update, and delete orders in Sendcloud.

​
Orders API behaviour and limits

Understanding how the Orders API behaves will help you design reliable synchronization logic.

​
Upsert behaviour

  • Orders are matched by order_id + order_details.integration.id
  • If a matching order exists, it is updated
  • If no match exists, a new order is created
  • You may optionally include Sendcloud’s internal id to explicitly target an existing order
When sending id, it must be a string — even though responses return it as a number

​
Batch processing

  • Up to 100 orders per request
  • Orders from multiple integrations may be included in the same batch
  • Requests are all-or-nothing: if one order fails validation, the entire batch is rejected

​
Constraints

  • order_id is immutable once an order exists
  • You can only create or update orders for integrations belonging to your account
  • Concurrent updates on the same order may result in a conflict — retry after a short delay

​
Creating orders

To create or update orders, make a POST request to:
Example request method and URL
POST https://panel.sendcloud.sc/api/v3/orders
This endpoint accepts an array of orders and applies upsert logic to each entry: if the order already exists, it is updated, if it does not exist, a new order is created. If the request is successful, the API returns HTTP 200 and a response body containing the created or updated orders, including their Sendcloud id. Orders created via the API typically include:
  • order_id
  • order_number
  • order_details.integration.id
  • Customer contact details
  • Shipping address or service point information
  • Order line items with quantities and pricing
  • Order totals and currency
  • Optional customs details (for international shipments)
Note: See the API Reference for the full schema.
Creating an order:
  • Does not create a shipment
  • Does not generate labels
  • Does not contact the carrier

​
Retrieving orders

To retrieve a list of orders, make a GET request to
Example request method and URL
GET https://panel.sendcloud.sc/api/v3/orders
The orders returned depend on:
  • The filters you provide (integration, order number, status, creation/update dates)
  • Sorting parameters
  • Page size settings
The endpoint is paginated. Use the next and prev links in the response headers to navigate through results. To retrieve an order, make a GET request including the specific id to:
Example request method and URL
GET https://panel.sendcloud.sc/api/v3/orders/{id}
This returns the order that matches the provided Sendcloud internal id.

​
Updating orders

You can keep Sendcloud synchronized with your source system by updating orders as data changes. This can be done either by reusing the upsert endpoint or by performing partial updates.

​
Upserting with POST (recommended)

To update an existing order, make a POST request to:
Example request method and URL
POST https://panel.sendcloud.sc/api/v3/orders
Include:
  • The same order_id
  • The same order_details.integration.id
  • Any fields that have changed (for example address corrections or status updates)
If a matching order exists, it will be updated. The internal Sendcloud id remains unchanged.

​
Partial updates

To update an order for specific fields only, make a PATCH request to:
Example request method and URL
PATCH https://panel.sendcloud.sc/api/v3/orders/{id}
Dedicated endpoints allow updating only specific fields of an order. See the API Reference for details on partial updates and supported fields.

​
Deleting orders

Orders that are cancelled upstream can be removed from Sendcloud. To delete an order, make a DELETE request to
Example request method and URL
DELETE https://panel.sendcloud.sc/api/v3/orders/{id}
Deleting an order:
  • Removes it from the Incoming Orders View
  • Does not affect shipments or labels that already exist

​
Error handling & troubleshooting

If a request fails validation, the API will return an error response. For batch requests:
  • If one order fails validation, the entire request is rejected
  • No orders are created or updated
Common causes of errors include:
  • Missing required fields
  • Invalid order_details.integration.id
  • Incorrect country codes or timestamps
  • Attempting to modify immutable fields such as order_id
  • Concurrent updates on the same order
If an order doesn’t appear or looks incorrect in the Sendcloud platform:
  • Confirm you received a success response
  • Confirm the response includes a Sendcloud id
  • Verify order_details.integration.id
  • Use GET /api/v3/orders/?integration={id} to confirm existence
  • Validate timestamps and country codes

​
Shipping an order (“Ship an Order” endpoints)

Orders do not generate labels or announce shipments by themselves. To ship an existing order, use the Ship an Order API. These endpoints generate shipping labels based on an order that already exists in Sendcloud.

Ship an Order API

Learn how to create shipping labels for your orders using the Ship an Order API.