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
filter object — Filtering by price-record fields.
Filtering syntax. Example: ?filter[productId]=101
select string — Field selection: ?select=id,productId,price. Only the listed fields are returned
sort string — Sort field. The - prefix means descending: ?sort=-price
limit number 50 Number of records (up to 5000)
offset number 0 Offset 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 app

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 app

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
success boolean Always true on success
data array Array of prices
data[].id number Price record identifier
data[].catalogGroupId number Price type. Base price is 1
data[].currency string Price currency, e.g. USD
data[].price number Price value
data[].productId number Identifier of the product the price belongs to
data[].quantityFrom number | null Lower bound of the quantity range. null if the price does not depend on quantity
data[].quantityTo number | null Upper bound of the quantity range. null if the price does not depend on quantity
data[].extraId number | null Markup identifier (catalog_extra). Deprecated Bitrix24 field
data[].priceScale number Price in the Bitrix24 account's base currency
data[].timestampX string Last modification date (ISO 8601)
meta.total number Total number of records matching the filter
meta.hasMore boolean Whether there are more records beyond limit

Response example

JSON 
{
  "success": true,
  "data": [
    {
      "catalogGroupId": 2,
      "currency": "USD",
      "extraId": null,
      "id": 5001,
      "price": 50,
      "priceScale": 50,
      "productId": 101,
      "quantityFrom": null,
      "quantityTo": null,
      "timestampX": "2024-06-17T16:53:24+00:00"
    },
    {
      "catalogGroupId": 1,
      "currency": "USD",
      "extraId": null,
      "id": 5002,
      "price": 10,
      "priceScale": 10,
      "productId": 102,
      "quantityFrom": null,
      "quantityTo": null,
      "timestampX": "2021-09-27T16:32:20+00:00"
    },
    {
      "catalogGroupId": 1,
      "currency": "USD",
      "extraId": null,
      "id": 5003,
      "price": 32999,
      "priceScale": 32999,
      "productId": 103,
      "quantityFrom": null,
      "quantityTo": null,
      "timestampX": "2025-01-10T14:49:59+00:00"
    }
  ],
  "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"
  }
}

Errors

HTTP Code Description
400 UNKNOWN_FILTER_FIELD Filtering by a field the price record does not have. The message contains the list of available fields
400 UNKNOWN_SORT_FIELD Sorting by a field the price record does not have. The message contains the list of available fields
403 SCOPE_DENIED The API key does not have the catalog scope
401 TOKEN_MISSING The X-Api-Key header was not provided

The full list of common API errors — Errors.

Known specifics

The extraId, priceScale and timestampX fields are not available for filtering and sorting. They appear in the response, but using them in filter or sort returns an error. Which fields are available — on the Catalog prices page.

See also