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

List prices

GET /v1/catalog-prices

Returns a list of product prices with support for filtering, sorting, field selection and pagination.

Parameters

Parameter Type Default Description
Parameterfilter Typeobject Default— DescriptionFiltering by price-record fields.
Filtering syntax. Example: ?filter[productId]=101
Parameterselect Typestring Default— DescriptionField selection: ?select=id,productId,price. Only the listed fields are returned
Parametersort Typestring Default— DescriptionSort field. The - prefix means descending: ?sort=-price. The same sort in the long form: ?order[price]=desc
Parameterlimit Typenumber Default50 DescriptionNumber of records (up to 5000)
Parameteroffset Typenumber Default0 DescriptionOffset from the start of the selection

For limit > 50, the response is automatically assembled from several pages on the server side. The maximum is 5000 records per call. If more records match the filter than were returned, meta.hasMore is true.

Examples

curl — personal key

Terminal 
curl "https://vibecode.bitrix24.com/v1/catalog-prices" \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth application

Terminal 
curl "https://vibecode.bitrix24.com/v1/catalog-prices" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/catalog-prices', {
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
  },
})

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

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/catalog-prices', {
  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 prices
Fielddata[].id Typenumber DescriptionPrice record identifier
Fielddata[].catalogGroupId Typenumber DescriptionPrice type. The number depends on the account — see price types
Fielddata[].currency Typestring DescriptionPrice currency, e.g. USD
Fielddata[].price Typenumber DescriptionPrice value
Fielddata[].productId Typenumber DescriptionIdentifier of the product the price belongs to
Fielddata[].quantityFrom Typenumber | null DescriptionLower bound of the quantity range. null if the price does not depend on quantity
Fielddata[].quantityTo Typenumber | null DescriptionUpper bound of the quantity range. null if the price does not depend on quantity
Fielddata[].extraId Typenumber | null DescriptionMarkup identifier (catalog_extra). Deprecated Bitrix24 field
Fielddata[].priceScale Typenumber DescriptionPrice in the Bitrix24 account's base currency
Fielddata[].timestampX Typestring DescriptionLast modification date (ISO 8601)
Fieldmeta.total Typenumber DescriptionTotal number of records matching the filter
Fieldmeta.hasMore Typeboolean DescriptionWhether there are more records beyond limit

Response example

JSON 
{
  "success": true,
  "data": [
    {
      "catalogGroupId": 1,
      "currency": "USD",
      "extraId": null,
      "id": 383,
      "price": 10,
      "priceScale": 10,
      "productId": 533,
      "quantityFrom": null,
      "quantityTo": null,
      "timestampX": "2021-09-27T13:32:20.000Z"
    },
    {
      "catalogGroupId": 1,
      "currency": "USD",
      "extraId": null,
      "id": 523,
      "price": 32999,
      "priceScale": 32999,
      "productId": 6595,
      "quantityFrom": null,
      "quantityTo": null,
      "timestampX": "2025-01-10T11:49:59.000Z"
    },
    {
      "catalogGroupId": 3,
      "currency": "USD",
      "extraId": null,
      "id": 535,
      "price": 100,
      "priceScale": 100,
      "productId": 6595,
      "quantityFrom": null,
      "quantityTo": null,
      "timestampX": "2024-06-17T13:53:57.000Z"
    }
  ],
  "meta": {
    "total": 85,
    "hasMore": true
  }
}

Error response example

400 — filtering by a nonexistent field:

JSON 
{
  "success": false,
  "error": {
    "code": "UNKNOWN_FILTER_FIELD",
    "message": "Unknown filter field 'bogusField' for entity 'catalog-prices'. Available: id, catalogGroupId, currency, price, productId, quantityFrom, quantityTo, priceScale, extraId, timestampX"
  }
}

Errors

HTTP Code Description
HTTP400 CodeUNKNOWN_FILTER_FIELD DescriptionFiltering by a field the price record does not have. The message contains the list of available fields
HTTP400 CodeUNKNOWN_SORT_FIELD DescriptionSorting by a field the price record does not have. The message contains the list of available fields
HTTP403 CodeSCOPE_DENIED DescriptionThe API key does not have the catalog scope
HTTP401 CodeTOKEN_MISSING DescriptionThe API key has no configured tokens
HTTP429 CodeRATE_LIMITED DescriptionRate limit exceeded: 300 requests per minute per portal. All API keys of the portal share one limit. 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

Filtering and sorting work on every field of the record, including the system fields extraId, priceScale and timestampX. The UNKNOWN_FILTER_FIELD message contains the field list.

Sorting. ?sort=-price — descending, the long form is ?order[price]=desc. Without the parameter, records are returned in ascending id order.

See also