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. The same sort in the long form: ?order[price]=desc
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 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
success boolean Always true on success
data array Array of prices
data[].id number Price record identifier
data[].catalogGroupId number Price type. The number depends on the account — see price types
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": 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
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 API key has no configured tokens
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

The full list of common API errors — Errors.

Known specifics

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

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

See also