## Search prices

`POST /v1/catalog-prices/search`

Search product prices by the conditions passed in the request body.

Unlike [`GET /v1/catalog-prices`](./list.md), the `filter`, `select`, `sort`, `limit` and `offset` parameters are passed in the JSON body rather than in the URL, which is more convenient for conditions across several fields. The response format is the same as for the list.

## Request fields (body)

| Parameter | Type | Default | Description |
|----------|-----|-----------|---------|
| `filter` | object | — | Filtering by price-record fields.<br>[Filtering syntax](/docs/filtering). Example: `{ "catalogGroupId": 1 }` |
| `select` | string[] | — | Field selection: `["id", "productId", "price"]`. Only the listed fields are returned |
| `sort` | string | — | Sort field. The `-` prefix means descending: `"-price"` |
| `limit` | number | `50` | Number of records (up to 5000) |
| `offset` | number | `0` | Offset from the start of the result set. Together with a date-range filter wider than 14 days it is rejected — see `UNSTABLE_OFFSET_PAGINATION` in the "Errors" section |
| `autoWindow` | boolean | `true` | Split the result set into weekly windows when filtering by a date range wider than 14 days. `false` disables splitting |

## Examples

### curl — personal key

```bash
curl -X POST "https://vibecode.bitrix24.com/v1/catalog-prices/search" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": { "catalogGroupId": 1 },
    "limit": 2
  }'
```

### curl — OAuth app

```bash
curl -X POST "https://vibecode.bitrix24.com/v1/catalog-prices/search" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": { "catalogGroupId": 1 },
    "limit": 2
  }'
```

### JavaScript — personal key

```javascript
const res = await fetch('https://vibecode.bitrix24.com/v1/catalog-prices/search', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    filter: { catalogGroupId: 1 },
    limit: 2,
  }),
})

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

### JavaScript — OAuth app

```javascript
const res = await fetch('https://vibecode.bitrix24.com/v1/catalog-prices/search', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    filter: { catalogGroupId: 1 },
    limit: 2,
  }),
})

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` |
| `meta.durationMs` | number | Request execution time in milliseconds |
| `meta.autoWindowed` | boolean | `true` if the result set was split into time windows |
| `meta.windowCount` | number | Number of windows. Present with `autoWindowed: true` |
| `meta.batchWaves` | number | Number of parallel request waves. Present with `autoWindowed: true` |

The `meta` fields sit next to `data`, not inside it. Pages must be walked by `meta.hasMore`: a `data` length equal to `limit` does not rule out the last page.

## Response example

```json
{
  "success": true,
  "data": [
    {
      "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": 22,
    "hasMore": true,
    "durationMs": 487
  }
}
```

With a date-range filter wider than 14 days, `meta` additionally returns `autoWindowed`, `windowCount`, and `batchWaves`:

```json
{
  "success": true,
  "data": [ /* ... */ ],
  "meta": {
    "total": 19,
    "hasMore": true,
    "autoWindowed": true,
    "windowCount": 131,
    "batchWaves": 3,
    "durationMs": 1092
  }
}
```

## Error response example

400 — filtering by a nonexistent field:

```json
{
  "success": false,
  "error": {
    "code": "UNKNOWN_FILTER_FIELD",
    "message": "Unknown filter field 'bogus' 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 | `UNSTABLE_OFFSET_PAGINATION` | `offset` greater than zero together with a date-range filter wider than 14 days. Two different retrieval algorithms produce inconsistent results, so the request is rejected. Take everything in a single request with `limit` up to 5000, or pass `autoWindow: false` with sorting by `id`, or split the date range into parts yourself |
| 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](/docs/errors).

## Known specifics

**Time-window splitting.** A date-range filter wider than 14 days is automatically split into weekly windows executed in parallel waves, so the result set bypasses the ceiling of 5000 records per call. `meta` then returns `autoWindowed: true`, the number of windows `windowCount`, and the number of waves `batchWaves`. The `autoWindow: false` parameter disables splitting. While splitting is active, an `offset` greater than zero is rejected with `UNSTABLE_OFFSET_PAGINATION`.

## See also

- [List prices](/docs/entities/catalog-prices/list)
- [Create a price](/docs/entities/catalog-prices/create)
- [Get a price](/docs/entities/catalog-prices/get)
- [Price fields](/docs/entities/catalog-prices/fields)
- [Filtering syntax](/docs/filtering)
- [Entities reference](/docs/entities-index)