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
Fieldfilter Typeobject Default— DescriptionFilter by fields from GET /v1/basket-item-properties/fields.
Filtering syntax. Example: { "basketId": 1001 }
Fieldselect Typestring | string[] Default— DescriptionAn array of field names or a comma-separated string. Only selected fields remain in data
Fieldsort Typestring | object | string[] Default— DescriptionSort as a string, an object, or an array of field names. A leading minus sign means descending order
Fieldorder Typeobject Default— DescriptionSort as an object. If sort is provided, it takes precedence
Fieldlimit Typenumber Default50 DescriptionNumber of records, from 1 to 5000. Defaults to 50. Zero becomes 50, a negative value becomes 1, and a value above 5000 becomes 5000
Fieldoffset Typenumber Default0 DescriptionNumber of records to skip. Defaults to 0
FieldwithTotal Typeboolean Default— DescriptionAccepted as true or false, but for basket item properties it changes neither the count nor the presence of meta.total
FieldautoWindow Typeboolean Default— DescriptionAccepts 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
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata Typearray DescriptionArray of matching properties. All fields: Basket item property fields. Empty when no records match
Fieldmeta.total Typenumber DescriptionTotal number of properties matching the filter
Fieldmeta.hasMore Typeboolean DescriptionWhether more records exist beyond the current batch
Fieldmeta.durationMs Typenumber DescriptionRequest duration in milliseconds
Fieldmeta.warnings Typearray DescriptionParameter warnings. Present only when warnings exist
Fieldmeta.pageErrorSample Typeobject DescriptionDetails 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
HTTP400 CodeUNKNOWN_FILTER_FIELD DescriptionThe filter contains a field absent from the schema. The message lists available fields
HTTP400 CodeINVALID_LIMIT Descriptionlimit has an unsupported type
HTTP400 CodeINVALID_SELECT_TYPE Descriptionselect is neither a string nor an array of strings
HTTP400 CodeINVALID_REQUEST DescriptionThe request body is not a JSON object
HTTP422 CodeBITRIX_ERROR DescriptionBitrix24 rejected the request. The reason is in error.message
HTTP503 CodeBITRIX_TIMEOUT DescriptionBitrix24 did not respond in time
HTTP502 CodeBITRIX_UNAVAILABLE DescriptionBitrix24 could not be reached
HTTP403 CodeSCOPE_DENIED DescriptionThe API key lacks the sale scope
HTTP401 CodeMISSING_API_KEY DescriptionThe X-Api-Key header is missing
HTTP401 CodeTOKEN_MISSING DescriptionNo Bitrix24 access tokens are configured
HTTP429 CodeRATE_LIMITED DescriptionThe 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