# Basket items

Manage product line items in orders: create, get, update, delete, search, aggregate. A basket item is a separate entity linked to an order by the `orderId` field. A single order may have several items — one per purchased product.

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

## Operations

- [Add an item](./basket-items/create.md) — `POST /v1/basket-items`
- [List items](./basket-items/list.md) — `GET /v1/basket-items`
- [Get an item](./basket-items/get.md) — `GET /v1/basket-items/:id`
- [Update an item](./basket-items/update.md) — `PATCH /v1/basket-items/:id`
- [Delete an item](./basket-items/delete.md) — `DELETE /v1/basket-items/:id`
- [Search items](./basket-items/search.md) — `POST /v1/basket-items/search`
- [Item fields](./basket-items/fields.md) — `GET /v1/basket-items/fields`
- [Aggregate items](./basket-items/aggregate.md) — `POST /v1/basket-items/aggregate`

## Key fields

| Field | Type | Description |
|------|-----|---------|
| `id` | number | Item identifier (read-only) |
| `orderId` | number | Required on create. Order identifier. Source: [`GET /v1/orders`](./orders/list.md) |
| `productId` | number | Required on create. Catalog product identifier. `0` — virtual item with no catalog link. Source: [`GET /v1/catalog-products`](/docs/entities/catalog-products) |
| `name` | string | Item name. For a catalog product, filled from the product card |
| `price` | number | Price per unit |
| `basePrice` | number | Base price before discount |
| `discountPrice` | number | Discount amount per unit |
| `quantity` | number | Required on create. Quantity |
| `currency` | string | Required on create. Item currency. List: [`GET /v1/currencies`](/docs/entities/currencies) |
| `vatRate` | number | VAT rate as a fraction of one (`0.20` = 20%) |
| `vatIncluded` | boolean | Whether VAT is included in the price |
| `weight` | number | Weight in grams |
| `dimensions` | string | Dimensions in PHP serialization format |
| `measureCode` | number | Measurement unit code (`796` = pcs, `163` = g, `006` = m, etc.) |
| `measureName` | string | Measurement unit name |
| `xmlId` | string | External item identifier |

Full field list — [`GET /v1/basket-items/fields`](./basket-items/fields.md).

## What to know before you start

1. **The request body is flat.** On create and update, pass fields directly at the root of the JSON: `{"orderId": 33, "productId": 119, ...}`. No `fields` wrapper is needed.
2. **Required fields on create.** Adding an item requires `orderId`, `productId`, `currency`, and `quantity`. The `orderId` field references an existing order — call [`POST /v1/orders`](./orders/create.md) first. The `productId` field links the item to a catalog product. The value `productId: 0` creates a virtual item with no catalog link — for it, `name` and `price` are set manually.
3. **`vatRate` is stored as a fraction of one.** For 20% VAT, pass `0.20`, not `20`. For 10%, `0.10`. For no VAT, `0` or omit it.
4. **Pass prices consistently.** `price` is the final price per unit including the discount, `basePrice` is before the discount, `discountPrice` is the discount amount. Bitrix24 does not recompute these fields against each other automatically. Pass `customPrice: true` so the item price is not updated when the catalog product price changes.

## Related entities

| Entity | Endpoint | Purpose |
|----------|----------|-----------|
| Orders | [`GET /v1/orders/:id`](./orders/get.md) | Parent order — `orderId` is set when the item is created. |
| Catalog products | [`GET /v1/catalog-products`](/docs/entities/catalog-products) | Source of `productId` for linking an item to a product. |
| Payments | [`GET /v1/payments?filter[orderId]=:id`](./payments.md) | Payments for the same order. |

## Typical scenario

Adding products to an order from an external system:

1. Create an order: [`POST /v1/orders`](./orders/create.md) — get `orderId`.
2. Find products in the catalog: [`GET /v1/catalog-products`](/docs/entities/catalog-products) — get `productId` for each item.
3. Add items: loop [`POST /v1/basket-items`](./basket-items/create.md) with `orderId`, `productId`, `quantity`, `price`, `currency`, `vatRate`.
4. Register a payment: [`POST /v1/payments`](./payments/create.md).

## Limits

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

- [Item fields](./basket-items/fields.md)
- [Orders](./orders.md)
- [Payments](./payments.md)
- [Catalog products](/docs/entities/catalog-products)
- [Entity API](/docs/entity-api)
- [Filtering syntax](/docs/filtering)
- [Batch](/docs/batch)
- [Entities reference](/docs/entities-index)