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, and 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 application

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 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
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata Typeobject DescriptionBasket item metadata
Fielddata.fields Typeobject DescriptionField definitions. Each key is a field name and each value describes the field. All fields are listed in the table below
Fielddata.fields.<field>.type Typestring DescriptionValue type: number, string, boolean, datetime or array
Fielddata.fields.<field>.readonly Typeboolean Descriptiontrue marks a read-only field
Fielddata.fields.<field>.nullable Typeboolean DescriptionPresent as true for fields that accept null
Fielddata.fields.<field>.label Typestring DescriptionField label
Fielddata.fields.<field>.description Typestring DescriptionField description
Fielddata.fields.<field>.itemSchema Typeobject DescriptionArray element schema. Present for properties and reservations
Fielddata.aggregatable Typearray DescriptionFields for groupBy in aggregation: price, quantity, currency, orderId, productId
Fielddata.batch Typearray DescriptionBatch 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
Fieldid Typenumber ROyes DescriptionItem identifier
FieldorderId Typenumber | null ROno DescriptionOrder identifier. Source: GET /v1/orders. null for standalone items with no order
FieldproductId Typenumber ROno DescriptionCatalog product identifier. Source: GET /v1/catalog-products. 0 — virtual item with no catalog link
Fieldname Typestring ROno DescriptionItem name
Fieldprice Typenumber ROno DescriptionPrice per unit after the discount
FieldbasePrice Typenumber ROno DescriptionBase price before discount
FielddiscountPrice Typenumber ROno DescriptionDiscount amount per unit
FieldcustomPrice Typeboolean ROno DescriptionThe price is set manually and is not recalculated when the product changes in the catalog
Fieldcurrency Typestring ROno DescriptionItem currency. List: GET /v1/currencies
Fieldquantity Typenumber ROno DescriptionQuantity
Fieldsort Typenumber ROno DescriptionItem sort order in the basket. Defaults to 100
Fieldweight Typenumber | null ROno DescriptionUnit weight in grams. null for items with no weight
Fielddimensions Typestring | null ROno DescriptionDimensions in PHP serialization format. null for items with no dimensions
FieldmeasureCode Typenumber | null ROno DescriptionMeasurement unit code. 796 — pcs, 163 — g, 006 — m. May be null
FieldmeasureName Typestring | null ROno DescriptionMeasurement unit name. May be null
FieldcanBuy Typeboolean ROno DescriptionWhether the item is available for purchase
FieldvatRate Typenumber | null ROno DescriptionVAT rate as a decimal fraction. 0.20 = 20%. null for items with no VAT
FieldvatIncluded Typeboolean ROno DescriptionWhether VAT is included in the price
FieldxmlId Typestring ROno DescriptionExternal item identifier
FieldproductXmlId Typestring | null ROno DescriptionExternal product identifier. May be null
FieldcatalogXmlId Typestring | null ROno DescriptionExternal catalog identifier. May be null
FielddateInsert Typedatetime ROyes DescriptionCreation date
FielddateUpdate Typedatetime ROyes DescriptionLast modified date
FieldbarcodeMulti Typeboolean ROno DescriptionThe item is tracked across several barcodes
Fieldtype Typestring | null ROyes DescriptionItem type. Always null on live Bitrix24 accounts
Fieldproperties Typearray ROyes DescriptionItem properties. Each element: {basketId, code, id, name, sort, value, xmlId}. Returned only by GET /v1/basket-items/:id, not in the list
Fieldreservations Typearray ROyes DescriptionWarehouse 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
HTTP403 CodeSCOPE_DENIED DescriptionThe API key lacks the sale scope
HTTP401 CodeTOKEN_MISSING DescriptionThe API key has no configured tokens
HTTP429 CodeRATE_LIMITED DescriptionRate 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.

See also