> ## Documentation Index
> Fetch the complete documentation index at: https://sendcloud.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Creating and managing orders

You can use the [Orders API](/api/v3/orders) 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

<Warning>When sending `id`, it must be a string — even though responses return it as a number</Warning>

### 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](/api/v3/orders/create-update-orders-in-batch), make a `POST` request to:

```http Example request method and URL theme={null}
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)

<Info>Note: See the [API Reference](/api/v3/orders/create-update-orders-in-batch) for the full schema.</Info>

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](/api/v3/orders/retrieve-a-list-of-orders), make a `GET` request to

```http Example request method and URL theme={null}
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](/api/v3/orders/retrieve-an-order), make a GET request including the specific `id` to:

```http Example request method and URL theme={null}
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](/api/v3/orders/create-update-orders-in-batch), make a `POST` request to:

```http Example request method and URL theme={null}
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](/api/v3/orders/update-an-order) for specific fields only, make a `PATCH` request to:

```http Example request method and URL theme={null}
PATCH https://panel.sendcloud.sc/api/v3/orders/{id}
```

<Warning>
  Dedicated endpoints allow updating only specific fields of an order. See the [API
  Reference](/api/v3/orders/update-an-order) for details on partial updates and supported fields.
</Warning>

## Deleting orders

Orders that are cancelled upstream can be removed from Sendcloud. To [delete an order](/api/v3/orders/delete-an-order), make a `DELETE` request to

```http Example request method and URL theme={null}
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](/api/v3/ship-an-order). These endpoints generate shipping labels based on an order that already exists in Sendcloud.

<Card title="Ship an Order API" href="/docs/orders/ship-an-order" icon="box" horizontal>
  Learn how to create shipping labels for your orders using the Ship an Order API.
</Card>