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

List CRM products

GET /v1/products

Returns a list of CRM catalog products with support for filtering, sorting, and auto-pagination.

By default a list item contains the base product fields. Custom catalog properties PROPERTY_<N> arrive in the same item when you name each one in select.

Parameters

Parameter Type Default Description
limit number 50 Number of records (up to 5000). When limit > 50, the request is automatically assembled from multiple pages on the server side
offset number 0 Offset from the start of the result set
select string — Field selection: ?select=id,name,price,active. A custom catalog property is requested by its own name: ?select=id,name,price,PROPERTY_301. Property names are listed in CRM product fields
sort string — Sorting via the short syntax: ?sort=-sort, the minus means descending
order object — Sorting by the id, name, sort fields. Example: ?order[sort]=desc, ?order[name]=asc. The price and currency fields do not support sorting
filter object — Only exact equality and $in (IN-set) on the id, name, code, xmlId, active, sectionId, sort, description fields. Operators (>, >=, <, <=, !, %, $ne, $contains, $nin) and filtering by other fields (price, currency) are not supported — 400 UNSUPPORTED_FILTER is returned.
Filtering syntax. Example: ?filter[active]=true

Examples

curl — personal key

Terminal 
curl "https://vibecode.bitrix24.com/v1/products?filter[active]=true&order[sort]=desc&limit=10" \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth application

Terminal 
curl "https://vibecode.bitrix24.com/v1/products?filter[active]=true&order[sort]=desc&limit=10" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

JavaScript — personal key

javascript 
const params = new URLSearchParams({
  'filter[active]': 'true',
  'order[sort]': 'desc',
  limit: '10',
})
const res = await fetch(`https://vibecode.bitrix24.com/v1/products?${params}`, {
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
  },
})

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

JavaScript — OAuth application

javascript 
const params = new URLSearchParams({
  'filter[active]': 'true',
  'order[sort]': 'desc',
  limit: '10',
})
const res = await fetch(`https://vibecode.bitrix24.com/v1/products?${params}`, {
  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 products. For the item's field set, see CRM product fields
meta.total number Total number of records matching the filter
meta.hasMore boolean Whether there are more records beyond limit

In the online store of your Bitrix24 account, the card URL of any product from the data array is built from its catalogId and id:

https://<portal>.bitrix24.com/shop/catalog/<catalogId>/product/<id>/

<portal> is the Bitrix24 portal domain. Access is restricted by the employee's permissions in Bitrix24.

Response example

JSON 
{
  "success": true,
  "data": [
    {
      "id": 6967,
      "name": "Master product",
      "code": "product_sku",
      "active": true,
      "previewPicture": null,
      "detailPicture": null,
      "sort": 100,
      "xmlId": "6967",
      "updatedAt": "2025-05-12T09:05:27.000Z",
      "createdAt": "2025-05-12T09:03:15.000Z",
      "modifyBy": 1,
      "createdBy": 1,
      "catalogId": 25,
      "sectionId": null,
      "description": null,
      "descriptionType": "text",
      "price": 100,
      "currency": "USD",
      "vatId": null,
      "vatIncluded": false,
      "measure": null
    },
    {
      "id": 533,
      "name": "test",
      "code": "test",
      "active": true,
      "previewPicture": null,
      "detailPicture": null,
      "sort": 500,
      "xmlId": "533",
      "updatedAt": "2023-08-21T09:12:18.000Z",
      "createdAt": "2021-07-20T11:01:36.000Z",
      "modifyBy": 29,
      "createdBy": 99,
      "catalogId": 25,
      "sectionId": 19,
      "description": null,
      "descriptionType": "html",
      "price": 10,
      "currency": "USD",
      "vatId": 1,
      "vatIncluded": false,
      "measure": 9
    }
  ],
  "meta": {
    "total": 19,
    "hasMore": true
  }
}

Error response example

400 — operator or unsupported field in the filter:

JSON 
{
  "success": false,
  "error": {
    "code": "UNSUPPORTED_FILTER",
    "message": "UNSUPPORTED_FILTER: 'price' is not filterable on 'products'. Its Bitrix24 method (crm.product.list) filters by exact match only. Filterable: id, name, code, xmlId, active, sectionId, sort, description."
  }
}

Errors

HTTP Code Description
400 UNSUPPORTED_FILTER Operator or unsupported field in the filter. Filter by exact equality or $in on id, name, code, xmlId, active, sectionId, sort, description
400 INVALID_FILTER Error in the filter syntax
400 UNKNOWN_SELECT_FIELD select carries a name the product does not have. The message lists the allowed names after the word Available
400 SELECT_FIELD_NOT_RETURNED select carries a name that CRM product fields shows with notReturned: true — currencyId, for example. Drop it from select
403 SCOPE_DENIED The API key does not have the crm scope
401 MISSING_API_KEY The X-Api-Key header was not passed
429 RATE_LIMITED Rate limit exceeded: 300 requests per minute per portal, all API keys of the portal share one limit. The exact value arrives in the x-ratelimit-limit header (the cap is divided across replicas). Retry after the delay in the Retry-After header

For the full list of common API errors, see Errors.

Known specifics

Catalog properties arrive only when named. Name every property you need in select — ?select=id,name,PROPERTY_295,PROPERTY_297. The value select=* does not return them; it returns the base product fields. An unset property arrives as a key with null, a filled one as an object { "valueId": …, "value": … }, the same as in Get CRM product.

The property number is not validated. A name of the form PROPERTY_<N> is accepted with any number. When the Bitrix24 account has no property with that number, the key does not arrive in the response, and there is neither a rejection nor a warning. The numbers in use are in CRM product fields.

See also