For AI agents: markdown of this page — /docs-content-en/entities/basket-items/fields.md documentation index — /llms.txt

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

Terminal

curl "https://vibecode.bitrix24.com/v1/basket-items/fields" \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth app

Terminal

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`. For standalone items with no order — `null`
`productId`	number	Catalog product identifier. Source: `GET /v1/catalog-products`. `0` — virtual item with no catalog link
`name`	string	Item name
`price`	number	Price per unit after 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`
`quantity`	number	Quantity
`sort`	number	Item sort 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 decimal fraction. `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	Last modified date (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

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 remains the raw Bitrix24 value directory for enumeration fields and is not used for an 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. They are omitted from the example below 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: