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

Search basket item properties

POST /v1/basket-item-properties/search

Searches basket item properties using filter and sort conditions sent in the JSON request body. Unlike the GET /v1/basket-item-properties list endpoint, it accepts search parameters in the body rather than the URL.

Request body fields

Field Type Default Description
filter object — Filter by fields from GET /v1/basket-item-properties/fields.
Filtering syntax. Example: { "basketId": 1001 }
select string | string[] — An array of field names or a comma-separated string. Only selected fields remain in data
sort string | object | string[] — Sort as a string, an object, or an array of field names. A leading minus sign means descending order
order object — Sort as an object. If sort is provided, it takes precedence
limit number 50 Number of records, from 1 to 5000. Defaults to 50. Zero becomes 50, a negative value becomes 1, and a value above 5000 becomes 5000
offset number 0 Number of records to skip. Defaults to 0
withTotal boolean — Accepted as true or false, but for basket item properties it changes neither the count nor the presence of meta.total
autoWindow boolean — Accepts true and false

Pagination. With limit > 50, Vibecode reads multiple pages of 50 records. For the next batch, increase offset by the number of records received. Continue while meta.hasMore is true.

Examples

curl — personal key

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/basket-item-properties/search" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"filter":{"basketId":1001},"select":["id","name","value"],"sort":"-id","limit":2}'

curl — OAuth application

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/basket-item-properties/search" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"filter":{"basketId":1001},"select":["id","name","value"],"sort":"-id","limit":2}'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/basket-item-properties/search', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "filter": {
      "basketId": 1001
    },
    "select": [
      "id",
      "name",
      "value"
    ],
    "sort": "-id",
    "limit": 2
  }),
})

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

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/basket-item-properties/search', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "filter": {
      "basketId": 1001
    },
    "select": [
      "id",
      "name",
      "value"
    ],
    "sort": "-id",
    "limit": 2
  }),
})

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

Response fields

Field Type Description
success boolean Always true on success
data array Array of matching properties. All fields: Basket item property fields. Empty when no records match
meta.total number Total number of properties matching the filter
meta.hasMore boolean Whether more records exist beyond the current batch
meta.durationMs number Request duration in milliseconds
meta.warnings array Parameter warnings. Present only when warnings exist
meta.pageErrorSample object Details of an error while reading subsequent pages. Present when such an error occurs

Response example

JSON 
{
  "success": true,
  "data": [
    {
      "id": 1007,
      "name": "Product XML_ID",
      "value": "6967"
    },
    {
      "id": 1005,
      "name": "Catalog XML_ID",
      "value": "FUTURE-1C-CATALOG"
    }
  ],
  "meta": {
    "total": 2,
    "hasMore": false,
    "durationMs": 64
  }
}

Error response example

400 — filter by an unknown field:

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

Errors

HTTP Code Description
400 UNKNOWN_FILTER_FIELD The filter contains a field absent from the schema. The message lists available fields
400 INVALID_LIMIT limit has an unsupported type
400 INVALID_SELECT_TYPE select is neither a string nor an array of strings
400 INVALID_REQUEST The request body is not a JSON object
422 BITRIX_ERROR Bitrix24 rejected the request. The reason is in error.message
503 BITRIX_TIMEOUT Bitrix24 did not respond in time
502 BITRIX_UNAVAILABLE Bitrix24 could not be reached
403 SCOPE_DENIED The API key lacks 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 The request rate limit was exceeded. Retry after the interval in the Retry-After header

For the full list of common API errors, see Error codes.

See also