# Orders

Online store order management: create, get, update, delete, search, aggregate. An order is the root entity of an online store: it begins the buyer's journey and ties together basket items, payments, shipments, and statuses.

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

## Operations

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

## Key fields

| Field | Type | Description |
|------|-----|---------|
| `id` | number | Order identifier (read-only) |
| `accountNumber` | string | Account number for the buyer — the order's sequential number in the Bitrix24 account |
| `lid` | string | Source site identifier, always `"s1"` for cloud portals |
| `personTypeId` | number | Payer-type identifier (legal entity, individual, etc.). Each Bitrix24 account has its own set of types. Find the ID from existing orders: `GET /v1/orders` or `POST /v1/orders/aggregate` with `groupBy: "personTypeId"` |
| `currency` | string | Order currency. List: [`GET /v1/currencies`](/docs/entities/currencies) |
| `price` | number | Total order amount |
| `statusId` | string | Current order status. Source: [`GET /v1/order-statuses?filter[type]=O`](./order-statuses/list.md) |
| `userId` | number | Bitrix24 user identifier — the buyer in the online store. Source: [`GET /v1/users`](/docs/entities/users) |
| `payed` | boolean | Whether the order is fully paid |
| `canceled` | boolean | Whether the order is canceled |
| `responsibleId` | number | Responsible employee. Source: [`GET /v1/users`](/docs/entities/users) |
| `dateInsert` | datetime | Creation date (read-only) |
| `dateUpdate` | datetime | Last modification date (read-only) |

Full field list — [`GET /v1/orders/fields`](./orders/fields.md).

## What you need to know before working

1. **The request body is flat.** When creating and updating, pass fields directly at the root of the JSON: `{"lid": "s1", "personTypeId": 5, ...}`. No `fields` wrapper is needed.
2. **Three fields are required to create:** `lid` (always `"s1"` for cloud portals), `personTypeId` (payer type — each Bitrix24 account has its own set), `currency`. Without them, `POST /v1/orders` returns `BITRIX_ERROR` listing the missing fields.
3. **An order returns related entities nested.** `GET /v1/orders/:id` returns the arrays `basketItems[]` (basket items), `payments[]` (payments), `propertyValues[]` (order properties), `clients[]` (CRM bindings) inside a single object. The separate endpoints [`/v1/basket-items`](./basket-items.md) and [`/v1/payments`](./payments.md) are used to create and update — but to read the contents of a single order, separate calls are not needed.
4. **Auto-pagination** is enabled when `limit > 50`. The total count comes in `meta.total`.

## Related entities

A full order lifecycle uses the `sale.*` entity family:

| Entity | Endpoint | Purpose |
|----------|----------|-----------|
| Basket items | [`GET /v1/basket-items?filter[orderId]=:id`](./basket-items.md) | The order's product items — what the buyer purchased, at what price, with what discount. |
| Payments | [`GET /v1/payments?filter[orderId]=:id`](./payments.md) | The order's payments — amount, payment system, "paid / refunded" status. |
| Order statuses | [`GET /v1/order-statuses?filter[type]=O`](./order-statuses.md) | Status catalog for filling `statusId`. Type `O` — order statuses, `D` — delivery statuses. |

## Typical scenario

Processing a new order from an external system (CMS, marketplace):

1. Get the list of order statuses: [`GET /v1/order-statuses?filter[type]=O`](./order-statuses/list.md) — find the ID of the required status (for example, `N` — "Accepted").
2. Create the order: [`POST /v1/orders`](./orders/create.md) with a minimum of fields (`lid`, `personTypeId`, `currency`, `price`, `statusId`, `userId`).
3. Add basket items: [`POST /v1/basket-items`](./basket-items/create.md) — one item per product (`orderId`, `productId`, `quantity`, `price`).
4. Register a payment: [`POST /v1/payments`](./payments/create.md) — specifying `orderId`, `paySystemId`, `sum`.
5. As the order progresses — update the status: [`PATCH /v1/orders/:id`](./orders/update.md) with a new `statusId`.

## Limits

| Limit | Value |
|-------|----------|
| Maximum records per request | 5000 (`limit ≤ 5000`) |
| Auto-pagination | enabled when `limit > 50` |
| `offset` on large selections | `limit ≤ 500` recommended when `offset ≥ 2500` |
| 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

- [Basket items](./basket-items.md)
- [Payments](./payments.md)
- [Order statuses](./order-statuses.md)
- [Entity API](/docs/entity-api)
- [Filter syntax](/docs/filtering)
- [Batch](/docs/batch)
- [Entity reference](/docs/entities-index)