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

List basket item properties

GET /v1/basket-item-properties

Returns basket item properties with filtering, sorting and automatic pagination. To get the properties of one item, filter by its identifier.

Parameters

Parameter Type Default Description
filter object — Filter by the fields from GET /v1/basket-item-properties/fields: id, basketId, name, value, code, sort, xmlId.
Filtering syntax. Example: ?filter[basketId]=9. Source of basketId: GET /v1/basket-items
select string — Comma-separated fields: ?select=id,basketId,value. An unknown name does not cause an error and is reported in meta.warnings with the code UNKNOWN_SELECT_FIELD
sort string — Sorting in short syntax: ?sort=-id, a minus means descending
order object — Sorting as an object: ?order[id]=desc
limit number 50 Number of records, from 1 to 5000
offset number 0 Number of records to skip
withTotal string — Accepted as true or false, but for basket item properties it changes neither the count nor the presence of meta.total

Pagination. With limit > 50, Vibecode automatically reads several pages of 50 records and merges them into one response. For the next batch, increase offset by the number of records received. Continue while meta.hasMore is true.

Examples

curl — personal key

Terminal 
curl -g "https://vibecode.bitrix24.com/v1/basket-item-properties?filter[basketId]=9" \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth application

Terminal 
curl -g "https://vibecode.bitrix24.com/v1/basket-item-properties?filter[basketId]=9" \
  -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-item-properties?filter[basketId]=9', {
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
  },
})

const { success, data, meta } = await res.json()
console.log(`Item properties: ${meta.total}`)

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/basket-item-properties?filter[basketId]=9', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

const { success, data, meta } = await res.json()

Response fields

Field Type Description
success boolean Always true on success
data array Array of basket item properties
data[].id number Property ID
data[].basketId number Basket item ID. Source: GET /v1/basket-items
data[].name string Property name
data[].value string | null Property value
data[].code string | null Property symbolic code
data[].sort number Sort order of the property within the item
data[].xmlId string | null External ID
meta.total number Total number of properties matching the filter
meta.hasMore boolean Whether there are records beyond the current batch
meta.warnings array Parameter warnings, with the fields code, message, field. Present only when there are warnings

Response example

JSON 
{
  "success": true,
  "data": [
    {
      "basketId": 9,
      "code": "CATALOG.XML_ID",
      "id": 17,
      "name": "Catalog XML_ID",
      "sort": 100,
      "value": "FUTURE-ERP-CATALOG",
      "xmlId": "bx_5fc9f8c57ff3e"
    },
    {
      "basketId": 9,
      "code": "PRODUCT.XML_ID",
      "id": 19,
      "name": "Product XML_ID",
      "sort": 100,
      "value": "1000000475",
      "xmlId": "bx_5fc9f8c57ffb2"
    }
  ],
  "meta": {
    "total": 2,
    "hasMore": false
  }
}

Error response example

400 — filter by an unknown field:

JSON 
{
  "success": false,
  "error": {
    "code": "UNKNOWN_FILTER_FIELD",
    "message": "Unknown filter field 'foo' for entity 'basket-item-properties'. Available: id, basketId, name, value, code, sort, xmlId"
  }
}

Errors

HTTP Code Description
400 UNKNOWN_FILTER_FIELD Filter by a field that is not in the schema. The message lists the available fields
400 INVALID_FILTER_OPERATOR Unknown operator in a filter condition. The message lists the supported ones
400 INVALID_FILTER filter is written neither in brackets nor as a JSON object, one request mixes both forms, or the condition could not be applied
400 UNKNOWN_SORT_FIELD Sorting by a field that is not in the schema
400 INVALID_SORT_DIRECTION The direction in the sort object is not one of asc, desc, ASC, DESC
403 SCOPE_DENIED The API key does not have the sale scope
401 MISSING_API_KEY The X-Api-Key header is missing
401 TOKEN_MISSING No Bitrix24 access tokens are configured
429 RATE_LIMITED Request limit exceeded. The exact value is in the x-ratelimit-limit header. Retry after the time in the Retry-After header

Full list of common API errors — Error codes.

Known specifics

Properties of all items in an order. Properties have no order filter. First get the IDs of the order items: GET /v1/basket-items with the filter ?filter[orderId]=33&select=id, where orderId comes from GET /v1/orders. Then pass them as a list: ?filter[basketId][]=9&filter[basketId][]=1005.

Nonexistent item. A filter by the basketId of an item that does not exist in the Bitrix24 account returns an empty data with meta.total equal to 0, not an error.

See also