# Basket item properties

Properties of a specific basket item: name, value, symbolic code, and sort order.

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

## Operations

- [Create a basket item property](/docs/entities/basket-item-properties/create) — `POST /v1/basket-item-properties`
- [List basket item properties](/docs/entities/basket-item-properties/list) — `GET /v1/basket-item-properties`
- [Get a basket item property](/docs/entities/basket-item-properties/get) — `GET /v1/basket-item-properties/:id`
- [Update a basket item property](/docs/entities/basket-item-properties/update) — `PATCH /v1/basket-item-properties/:id`
- [Delete a basket item property](/docs/entities/basket-item-properties/delete) — `DELETE /v1/basket-item-properties/:id`
- [Search basket item properties](/docs/entities/basket-item-properties/search) — `POST /v1/basket-item-properties/search`
- [Basket item property fields](/docs/entities/basket-item-properties/fields) — `GET /v1/basket-item-properties/fields`
- [Aggregate basket item properties](/docs/entities/basket-item-properties/aggregate) — `POST /v1/basket-item-properties/aggregate`

## Key fields

| Field | Type | Description |
|------|-----|---------|
| `id` | number | Property ID. List: [`GET /v1/basket-item-properties`](./basket-item-properties/list.md). Read-only |
| `basketId` | number | Basket item ID from [`GET /v1/basket-items`](/docs/entities/basket-items/list). Required on creation, cannot be changed through `PATCH` |
| `name` | string | Property name. Required on creation |
| `value` | string \| null | Property value. Required on creation |
| `code` | string \| null | Property symbolic code. Required on creation |
| `sort` | number | Sort order of the property within the item |
| `xmlId` | string \| null | External ID |

For the complete field list, see [`GET /v1/basket-item-properties/fields`](./basket-item-properties/fields.md).

## Before you start

1. **Reading properties in an item and writing them use separate methods.** [`GET /v1/basket-items/:id`](/docs/entities/basket-items/get) returns properties in the read-only `properties` field. Use the methods in this section to create, update, and delete properties.
2. **Select an order's properties through its basket items.** Get item IDs using [`GET /v1/basket-items`](/docs/entities/basket-items/list) with an `orderId` filter. Source of `orderId`: [`GET /v1/orders`](/docs/entities/orders/list). Then pass the item IDs in the `basketId` filter of [list](./basket-item-properties/list.md) or [search](./basket-item-properties/search.md).
3. **Partial updates preserve omitted fields.** If `PATCH` omits `name`, `code`, or `value`, Vibecode reads the property and fills in the stored values. For batch updates, pass all three fields explicitly for each property. For the format, see [Batch calls](/docs/batch).
4. **Creating and deleting a property saves the order.** The order that owns the basket item has its `dateUpdate` and `version` updated.

## Typical workflow

1. Select a basket item and get its `id`: [`GET /v1/basket-items`](/docs/entities/basket-items/list).
2. Check its properties with a `basketId` filter: [`GET /v1/basket-item-properties`](./basket-item-properties/list.md).
3. Create a property with `basketId`, `name`, `value`, and `code`: [`POST /v1/basket-item-properties`](./basket-item-properties/create.md).
4. Read the property by its returned `id`: [`GET /v1/basket-item-properties/:id`](./basket-item-properties/get.md).
5. Update the value: [`PATCH /v1/basket-item-properties/:id`](./basket-item-properties/update.md).
6. Delete the property when it is no longer needed: [`DELETE /v1/basket-item-properties/:id`](./basket-item-properties/delete.md).

## Limits

| Limit | Value |
|-------|----------|
| Records per list or search request | `limit` from 1 to 5000, default 50. Use `offset` for the following records. See [List basket item properties](./basket-item-properties/list.md) and [Search basket item properties](./basket-item-properties/search.md) |
| Automatic pagination | With `limit > 50`, Vibecode reads Bitrix24 pages of 50 records and merges them into one response. See [List](./basket-item-properties/list.md) |
| Batch calls | `POST /v1/batch` and `POST /v1/basket-item-properties/batch`. Defaults: up to 500 items for writes and up to 50 calls for reads. Platform settings can change these limits. For the format, see [Batch calls](/docs/batch) |
| Request rate | Shared Vibecode API limit — see [Limits and optimization](/docs/optimization) |

## See also

- [Basket items](/docs/entities/basket-items)
- [Orders](/docs/entities/orders)
- [Filtering syntax](/docs/filtering)
- [Entity API](/docs/entity-api)
- [Batch calls](/docs/batch)