# Order statuses

Manage the order and delivery statuses of an online store: create, get, update, delete, search, aggregate. Statuses are a reference list that the [`orders.statusId`](./orders/fields.md) field points to. Each status has a type: `O` — order status, `D` — delivery status.

Bitrix24 API: `sale.status.*`
Scope: `sale`

## Operations

- [Create status](./order-statuses/create.md) — `POST /v1/order-statuses`
- [List statuses](./order-statuses/list.md) — `GET /v1/order-statuses`
- [Get status](./order-statuses/get.md) — `GET /v1/order-statuses/:id`
- [Update status](./order-statuses/update.md) — `PATCH /v1/order-statuses/:id`
- [Delete status](./order-statuses/delete.md) — `DELETE /v1/order-statuses/:id`
- [Search statuses](./order-statuses/search.md) — `POST /v1/order-statuses/search`
- [Status fields](./order-statuses/fields.md) — `GET /v1/order-statuses/fields`
- [Aggregate statuses](./order-statuses/aggregate.md) — `POST /v1/order-statuses/aggregate`

## Key fields

| Field | Type | Description |
|------|-----|---------|
| `id` | string | Status character code (1-2 characters: `N`, `IP`, `DT`). **Set by the user on creation**, not generated automatically |
| `type` | string | Status type: `O` — order status, `D` — delivery status |
| `sort` | number \| null | Sort order in lists. When created without `sort`, the field stays `null` — no default value is substituted |
| `notify` | boolean | Whether to send a notification to the customer when an order moves into this status. When created without `notify`, the field stays `false` — no default value is substituted |
| `color` | string \| null | HEX color code for display, for example `#FFA500`, or `null`. When created without `color`, the field stays `null` — no default value is substituted |
| `xmlId` | string \| null | External identifier. When created without an explicit value, it is generated automatically in the form `bx_<hash>`. Some system statuses have `null` |

Full list of fields — [`GET /v1/order-statuses/fields`](./order-statuses/fields.md).

There is no separate field with a localized status name through this API — the character code `id` and the type `type` serve to identify a status.

## What you need to know before working

1. **`id` is set by the user.** On creation, pass a short character code (1-2 characters): for example, `N` ("new"), `IP` ("in progress"), `DT` ("delivered"). The identifier must be unique regardless of type — you cannot create two statuses with the same `id`, even if one is for an order and the other for delivery.
2. **The request body is flat.** On create and update, pass fields directly at the root of the JSON: `{"id": "DT", "type": "O", ...}`. No `fields` wrapper is needed.
3. **Default set of statuses.** A new Bitrix24 account has standard statuses: `N` ("Accepted, awaiting payment"), `P` ("Paid"), `F` ("Completed"), `D` ("Declined"), `DN` ("Being delivered") and others. They can be modified and deleted through the same API, but orders that reference an old `id` no longer appear in queries filtered by `statusId` after the status is deleted.

## Related entities

| Entity | Endpoint | Purpose |
|----------|----------|-----------|
| Orders | [`GET /v1/orders?filter[statusId]=:id`](./orders/list.md) | Orders that are in this status — the `orders.statusId` field points here. |

## Typical scenario

Creating a new order status and using it:

1. Get existing statuses: [`GET /v1/order-statuses?filter[type]=O`](./order-statuses/list.md) — make sure the new `id` code is not taken.
2. Create the status: [`POST /v1/order-statuses`](./order-statuses/create.md) with `id`, `type: "O"`, `sort`, `notify`, `color`.
3. Use it in orders: [`PATCH /v1/orders/:id`](./orders/update.md) with `statusId: "new_id"`.

## Limits

| Limit | Value |
|-------|----------|
| Maximum records per request | 5000 (`limit ≤ 5000`) |
| Auto-pagination | enabled when `limit > 50` |
| `id` length | maximum 2 characters (status character code) |
| Batch requests | up to 50 operations in [`POST /v1/batch`](/docs/batch) |
| Rate limit | shared across the Vibecode API — see [Limits and optimization](/docs/optimization) |

## See also

- [Orders](./orders.md)
- [Entity API](/docs/entity-api)
- [Filtering syntax](/docs/filtering)
- [Batch](/docs/batch)
- [Entities reference](/docs/entities-index)