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 automatic paging.

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; a leading minus means descending. Supported fields: id, name, active, sort, sectionId, xmlId, code, description, descriptionType, createdBy, modifyBy, createdAt, updatedAt, plus catalog properties named PROPERTY_<n>
order object — Sorting in object form. Example: ?order[sort]=desc, ?order[name]=asc. price, currency, catalogId, measure, VAT fields and image fields cannot be sorted: every spelling, including the raw name PRICE, returns 400 UNKNOWN_SORT_FIELD with the supported-field list
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
include string — Related data: section — the catalog section the product belongs to. See the "Related data" section for details
withTotal string — Whether you need the count: true or false. false — do not request a count. This is the only way to guarantee that meta.total is absent from the response. Without the parameter: the API key setting applies, then the platform default — and in that case a short page still carries the exact count even without an explicit request. Paging and counts

Examples

curl — personal key

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

curl — OAuth application

Terminal 
curl -g "https://vibecode.bitrix24.com/v1/products?filter[active]=true&order[sort]=asc&limit=2" \
  -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]': 'asc',
  limit: '2',
})
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(`Received: ${data.length}, more available: ${meta.hasMore}`)

JavaScript — OAuth application

javascript 
const params = new URLSearchParams({
  'filter[active]': 'true',
  'order[sort]': 'asc',
  limit: '2',
})
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. An optional field: if no count was requested, it is absent from the response
meta.hasMore boolean Whether there are more records beyond limit
meta.includeSkipped boolean true if the response holds more than 200 records and the relations from include are not loaded. Reduce limit. With 200 records or fewer, the field is absent

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

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

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

The catalog section the product belongs to is returned in every array element when you request it through the include parameter:

GET /v1/products?filter[sectionId]=19&limit=1&include=section

The available value is section. The result is in the _included.section field of every data[] element. For a product outside any section, when sectionId is null, the response carries "section": null. If the response holds more than 200 records, relations are not loaded and meta carries includeSkipped: true — reduce limit. The example shows the sectionId field and the _included block:

JSON 
{
  "success": true,
  "data": [
    {
      "id": 533,
      "name": "test",
      "sectionId": 19,
      "_included": {
        "section": {
          "id": 19,
          "name": "Tours",
          "catalogId": 25,
          "sectionId": 31,
          "xmlId": null,
          "code": null
        }
      }
    }
  ],
  "meta": {
    "hasMore": true
  }
}

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": 6969,
      "name": "Service",
      "code": "service",
      "active": true,
      "previewPicture": null,
      "detailPicture": null,
      "sort": 100,
      "xmlId": "6969",
      "updatedAt": "2025-05-12T09:04:01.000Z",
      "createdAt": "2025-05-12T09:04:01.000Z",
      "modifyBy": 1,
      "createdBy": 1,
      "catalogId": 25,
      "sectionId": null,
      "description": null,
      "descriptionType": "text",
      "price": 250,
      "currency": "USD",
      "vatId": 1,
      "vatIncluded": true,
      "measure": null
    }
  ],
  "meta": {
    "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 INVALID_INCLUDE include carries a value other than section. The message lists the available values after the word Available
400 UNKNOWN_SORT_FIELD Sorting by a field the product cannot be sorted by — price, currency, catalogId, measure, VAT and image fields in any spelling, including the raw names PRICE and CATALOG_ID. The message lists the available fields after the word Available
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, shared by all API keys of the portal. 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 the value null, and 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