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
Parameterlimit Typenumber Default50 DescriptionNumber of records (up to 5000). When limit > 50, the request is automatically assembled from multiple pages on the server side
Parameteroffset Typenumber Default0 DescriptionOffset from the start of the result set
Parameterselect Typestring Default— DescriptionField 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
Parametersort Typestring Default— DescriptionSorting 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>
Parameterorder Typeobject Default— DescriptionSorting 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
Parameterfilter Typeobject Default— DescriptionOnly 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
Parameterinclude Typestring Default— DescriptionRelated data: section — the catalog section the product belongs to. See the "Related data" section for details
ParameterwithTotal Typestring Default— DescriptionWhether 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
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata Typearray DescriptionArray of products. For the item's field set, see CRM product fields
Fieldmeta.total Typenumber DescriptionTotal number of records matching the filter. An optional field: if no count was requested, it is absent from the response
Fieldmeta.hasMore Typeboolean DescriptionWhether there are more records beyond limit
Fieldmeta.includeSkipped Typeboolean Descriptiontrue 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
HTTP400 CodeUNSUPPORTED_FILTER DescriptionOperator or unsupported field in the filter. Filter by exact equality or $in on id, name, code, xmlId, active, sectionId, sort, description
HTTP400 CodeINVALID_FILTER DescriptionError in the filter syntax
HTTP400 CodeINVALID_INCLUDE Descriptioninclude carries a value other than section. The message lists the available values after the word Available
HTTP400 CodeUNKNOWN_SORT_FIELD DescriptionSorting 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
HTTP400 CodeUNKNOWN_SELECT_FIELD Descriptionselect carries a name the product does not have. The message lists the allowed names after the word Available
HTTP400 CodeSELECT_FIELD_NOT_RETURNED Descriptionselect carries a name that CRM product fields shows with notReturned: true — currencyId, for example. Drop it from select
HTTP403 CodeSCOPE_DENIED DescriptionThe API key does not have the crm scope
HTTP401 CodeMISSING_API_KEY DescriptionThe X-Api-Key header was not passed
HTTP429 CodeRATE_LIMITED DescriptionRate limit exceeded: 300 requests per minute per portal, shared by all API keys of the portal. The current limit is returned in the x-ratelimit-limit header. 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