## Basket item fields

`GET /v1/basket-items/fields`

Returns the basket item field schema: types, read-only flags, 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 app

```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 app

```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 |
|------|-----|---------|
| `id` | number | Item identifier (read-only) |
| `orderId` | number \| null | Order identifier. Source: [`GET /v1/orders`](../orders/list.md). For free items without an order — `null` |
| `productId` | number | Catalog product identifier. Source: [`GET /v1/catalog-products`](/docs/entities/catalog-products). `0` — virtual item with no catalog link |
| `name` | string | Item name |
| `price` | number | Price per unit including the discount |
| `basePrice` | number | Base price before discount |
| `discountPrice` | number | Discount amount per unit |
| `customPrice` | boolean | The price is set manually and is not recalculated when the product changes in the catalog |
| `currency` | string | Item currency. List: [`GET /v1/currencies`](/docs/entities/currencies) |
| `quantity` | number | Quantity |
| `sort` | number | Item order in the basket. Defaults to `100` |
| `weight` | number \| null | Unit weight in grams. `null` for items with no weight |
| `dimensions` | string \| null | Dimensions in PHP serialization format. `null` for items with no dimensions |
| `measureCode` | number \| null | Measurement unit code. `796` — pcs, `163` — g, `006` — m. May be `null` |
| `measureName` | string \| null | Measurement unit name. May be `null` |
| `canBuy` | boolean | Whether the item is available for purchase |
| `vatRate` | number \| null | VAT rate as a fraction of one. `0.20` = 20%. `null` for items with no VAT |
| `vatIncluded` | boolean | Whether VAT is included in the price |
| `xmlId` | string | External item identifier |
| `productXmlId` | string \| null | External product identifier. May be `null` |
| `catalogXmlId` | string \| null | External catalog identifier. May be `null` |
| `dateInsert` | datetime | Creation date (read-only) |
| `dateUpdate` | datetime | Date of last change (read-only) |
| `barcodeMulti` | boolean | The item is tracked across several barcodes |
| `type` | string \| null | Item type (read-only). Always `null` on live Bitrix24 accounts |
| `properties` | array | Item properties, read-only. Each element: `{basketId, code, id, name, sort, value, xmlId}`. Returned only by `GET /v1/basket-items/:id`, not in the list |
| `reservations` | array | Warehouse reservations for the item, read-only. Returned only by `GET /v1/basket-items/:id`, not in the list |

## Response example

```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 },
      "reservations": { "type": "array", "readonly": true }
    },
    "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 |

For the full list of common API errors, see [Errors](/docs/errors).

## See also

- [List items](./list.md)
- [Add item](./create.md)
- [Aggregate items](./aggregate.md)
- [Entity API](/docs/entity-api)