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

List basket items

GET /v1/basket-items

Returns a list of basket items with filtering and auto-pagination support.

Parameters

Parameter Type Default Description
limit number 50 Number of records (up to 5000). When limit > 50, Vibecode automatically requests several pages from Bitrix24
offset number 0 Skip N records. When offset ≥ 2500, limit ≤ 500 is recommended
select string — Field selection: ?select=id,orderId,name,quantity,price
order object — Sorting: ?order[id]=desc
filter object — Filtering by key item fields.
Filtering syntax. Example: ?filter[orderId]=33

Examples

curl — personal key

Terminal 
curl "https://vibecode.bitrix24.com/v1/basket-items?limit=10&filter[orderId]=33" \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth app

Terminal 
curl "https://vibecode.bitrix24.com/v1/basket-items?limit=10&filter[orderId]=33" \
  -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?limit=10&filter[orderId]=33', {
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
  },
})

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

JavaScript — OAuth app

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/basket-items?limit=10&filter[orderId]=33', {
  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 items
meta.total number Total number of records matching the filter
meta.hasMore boolean Whether there are more records beyond limit

Response example

JSON 
{
  "success": true,
  "data": [
    {
      "id": 9,
      "orderId": 33,
      "productId": 119,
      "name": "Home Slippers Favorite Sport",
      "price": 470,
      "basePrice": 470,
      "discountPrice": 0,
      "currency": "USD",
      "quantity": 1,
      "weight": 0,
      "vatRate": 0,
      "vatIncluded": true,
      "measureCode": 796,
      "measureName": "pcs",
      "xmlId": "bx_5fc9f8c57fe6c",
      "productXmlId": "1000000475",
      "catalogXmlId": "FUTURE-ERP-CATALOG",
      "canBuy": true,
      "dateInsert": "2020-12-04T07:52:21.000Z",
      "dateUpdate": "2022-11-02T05:10:13.000Z"
    }
  ],
  "meta": {
    "total": 1,
    "hasMore": false
  }
}

The main fields are shown. For the full item response, see GET /v1/basket-items/:id.

Error response example

400 — filter by a non-existent field:

JSON 
{
  "success": false,
  "error": {
    "code": "UNKNOWN_FILTER_FIELD",
    "message": "Unknown filter field 'foo' for entity 'basket-items'. Available: …"
  }
}

Errors

HTTP Code Description
400 UNKNOWN_FILTER_FIELD Filter by a field not in the schema
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.

Known specifics

Auto-pagination: when limit > 50, Vibecode automatically requests several pages from Bitrix24 and returns all records in a single response.

Free items without an order. Some items in data[] may have orderId: null — these are items in buyers' unfinished baskets, not yet placed into an order. To exclude them, add filter[orderId][!]=null or filter by a specific orderId.

See also