## Basket item fields `GET /v1/basket-items/fields` Returns the basket item field schema: types, read-only flags, and the list of aggregatable fields. ## Examples ### curl — personal key ```bash curl "https://vibecode.bitrix24.com/v1/basket-items/fields" \ -H "X-Api-Key: YOUR_API_KEY" ``` ### curl — OAuth application ```bash curl "https://vibecode.bitrix24.com/v1/basket-items/fields" \ -H "X-Api-Key: YOUR_APP_KEY" \ -H "Authorization: Bearer USER_SESSION_TOKEN" ``` ### JavaScript — personal key ```javascript const res = await fetch('https://vibecode.bitrix24.com/v1/basket-items/fields', { headers: { 'X-Api-Key': 'YOUR_API_KEY', }, }) const { data } = await res.json() console.log('Item fields:', Object.keys(data.fields)) ``` ### JavaScript — OAuth application ```javascript const res = await fetch('https://vibecode.bitrix24.com/v1/basket-items/fields', { headers: { 'X-Api-Key': 'YOUR_APP_KEY', 'Authorization': 'Bearer USER_SESSION_TOKEN', }, }) const { data } = await res.json() ``` ## Response fields | Field | Type | Description | |------|-----|---------| | `success` | boolean | Always `true` on success | | `data` | object | Basket item metadata | | `data.fields` | object | Field definitions. Each key is a field name and each value describes the field. All fields are listed in the table below | | `data.fields..type` | string | Value type: `number`, `string`, `boolean`, `datetime` or `array` | | `data.fields..readonly` | boolean | `true` marks a read-only field | | `data.fields..nullable` | boolean | Present as `true` for fields that accept `null` | | `data.fields..label` | string | Field label | | `data.fields..description` | string | Field description | | `data.fields..itemSchema` | object | Array element schema. Present for `properties` and `reservations` | | `data.aggregatable` | array | Fields for `groupBy` in [aggregation](/docs/entities/basket-items/aggregate): `price`, `quantity`, `currency`, `orderId`, `productId` | | `data.batch` | array | Batch write operations: `create`, `update`, `delete` | ### Basket item fields The complete set of fields in the `data.fields` map. RO marks a read-only field. | Field | Type | RO | Description | |------|-----|:--:|---------| | `id` | number | yes | Item identifier | | `orderId` | number \| null | no | Order identifier. Source: [`GET /v1/orders`](../orders/list.md). `null` for standalone items with no order | | `productId` | number | no | Catalog product identifier. Source: [`GET /v1/catalog-products`](/docs/entities/catalog-products). `0` — virtual item with no catalog link | | `name` | string | no | Item name | | `price` | number | no | Price per unit after the discount | | `basePrice` | number | no | Base price before discount | | `discountPrice` | number | no | Discount amount per unit | | `customPrice` | boolean | no | The price is set manually and is not recalculated when the product changes in the catalog | | `currency` | string | no | Item currency. List: [`GET /v1/currencies`](/docs/entities/currencies) | | `quantity` | number | no | Quantity | | `sort` | number | no | Item sort order in the basket. Defaults to `100` | | `weight` | number \| null | no | Unit weight in grams. `null` for items with no weight | | `dimensions` | string \| null | no | Dimensions in PHP serialization format. `null` for items with no dimensions | | `measureCode` | number \| null | no | Measurement unit code. `796` — pcs, `163` — g, `006` — m. May be `null` | | `measureName` | string \| null | no | Measurement unit name. May be `null` | | `canBuy` | boolean | no | Whether the item is available for purchase | | `vatRate` | number \| null | no | VAT rate as a decimal fraction. `0.20` = 20%. `null` for items with no VAT | | `vatIncluded` | boolean | no | Whether VAT is included in the price | | `xmlId` | string | no | External item identifier | | `productXmlId` | string \| null | no | External product identifier. May be `null` | | `catalogXmlId` | string \| null | no | External catalog identifier. May be `null` | | `dateInsert` | datetime | yes | Creation date | | `dateUpdate` | datetime | yes | Last modified date | | `barcodeMulti` | boolean | no | The item is tracked across several barcodes | | `type` | string \| null | yes | Item type. Always `null` on live Bitrix24 accounts | | `properties` | array | yes | Item properties. Each element: `{basketId, code, id, name, sort, value, xmlId}`. Returned only by `GET /v1/basket-items/:id`, not in the list | | `reservations` | array | yes | Warehouse reservations for the item. Returned only by `GET /v1/basket-items/:id`, not in the list | For arrays with a declared element shape, the `/fields` response contains `itemSchema`. `properties.itemSchema.properties` lists the item property fields, while only the `object` type is known for `reservations.itemSchema`. The separate `items` key contains the raw Bitrix24 lookup values for enumeration fields and is not used as the element schema. ## Response example Besides `type` and `readonly`, every field carries a `label` (short name) and a `description` (explanation), both in English. Request headers do not switch the language. The example below omits `label` and `description` for brevity. Nested `itemSchema.properties` maps are also shortened to a few representative fields; the live response contains the full entity-schema set. ```json { "success": true, "data": { "fields": { "id": { "type": "number", "readonly": true }, "orderId": { "type": "number", "readonly": false }, "productId": { "type": "number", "readonly": false }, "name": { "type": "string", "readonly": false }, "price": { "type": "number", "readonly": false }, "basePrice": { "type": "number", "readonly": false }, "discountPrice": { "type": "number", "readonly": false }, "customPrice": { "type": "boolean", "readonly": false }, "currency": { "type": "string", "readonly": false }, "quantity": { "type": "number", "readonly": false }, "sort": { "type": "number", "readonly": false }, "weight": { "type": "number", "readonly": false, "nullable": true }, "dimensions": { "type": "string", "readonly": false, "nullable": true }, "measureCode": { "type": "number", "readonly": false, "nullable": true }, "measureName": { "type": "string", "readonly": false, "nullable": true }, "canBuy": { "type": "boolean", "readonly": false }, "vatRate": { "type": "number", "readonly": false, "nullable": true }, "vatIncluded": { "type": "boolean", "readonly": false }, "xmlId": { "type": "string", "readonly": false }, "productXmlId": { "type": "string", "readonly": false, "nullable": true }, "catalogXmlId": { "type": "string", "readonly": false, "nullable": true }, "dateInsert": { "type": "datetime", "readonly": true }, "dateUpdate": { "type": "datetime", "readonly": true }, "barcodeMulti": { "type": "boolean", "readonly": false }, "type": { "type": "string", "readonly": true }, "properties": { "type": "array", "readonly": true, "itemSchema": { "type": "object", "properties": { "basketId": { "type": "number" }, "code": { "type": "string", "nullable": true }, "value": { "type": "string" } } } }, "reservations": { "type": "array", "readonly": true, "itemSchema": { "type": "object" } } }, "aggregatable": ["price", "quantity", "currency", "orderId", "productId"], "batch": ["create", "update", "delete"] } } ``` ## Error response example 403 — no scope: ```json { "success": false, "error": { "code": "SCOPE_DENIED", "message": "This endpoint requires 'sale' scope" } } ``` ## Errors | HTTP | Code | Description | |------|-----|---------| | 403 | `SCOPE_DENIED` | The API key lacks the `sale` scope | | 401 | `TOKEN_MISSING` | The API key has no configured tokens | | 429 | `RATE_LIMITED` | Rate limit exceeded: 300 requests per minute per portal. All API keys of the portal share one limit. The current limit is returned in the `x-ratelimit-limit` header. Retry after the delay in the `Retry-After` header | For the full list of common API errors, see [Errors](/docs/errors). ## See also - [List items](./list.md) - [Add item](./create.md) - [Aggregate basket items](./aggregate.md) - [Entity API](/docs/entity-api)