## List price types

`GET /v1/catalog-price-types`

Returns the price types configured in your Bitrix24 account, with filtering, sorting and field selection.

## Parameters

| Parameter | Type | Default | Description |
|----------|-----|-----------|---------|
| `limit` | number | `50` | Number of records (up to 5000). With `limit > 50` the response is assembled automatically from several Bitrix24 pages |
| `offset` | number | `0` | Skip N records. Together with `limit` it defines the selection window |
| `select` | string | — | Field selection: `?select=id,name,base`. Only the listed fields are returned |
| `sort` | string | — | Sort field. The `-` prefix means descending: `?sort=-sort`. The same sort in the long form: `?order[sort]=desc` |
| `filter` | object | — | Filtering by the fields of `GET /v1/catalog-price-types/fields`.<br>[Filtering syntax](/docs/filtering). Example: `?filter[base]=Y` |

## Examples

### curl — personal key

```bash
curl "https://vibecode.bitrix24.com/v1/catalog-price-types" \
  -H "X-Api-Key: YOUR_API_KEY"
```

### curl — OAuth application

```bash
curl "https://vibecode.bitrix24.com/v1/catalog-price-types" \
  -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-price-types', {
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
  },
})

const { success, data, meta } = await res.json()
const basePriceType = data.find(t => t.base === 'Y')
console.log('catalogGroupId of the base price:', basePriceType.id)
```

### JavaScript — OAuth application

```javascript
const res = await fetch('https://vibecode.bitrix24.com/v1/catalog-price-types', {
  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 price types (all fields — see [Price type fields](/docs/entities/catalog-price-types/fields)) |
| `meta.total` | number | Total number of price types matching the filter |
| `meta.hasMore` | boolean | Whether more records exist beyond `limit` |

## Response example

The response to `GET /v1/catalog-price-types?limit=2` — two of the five price types configured on the account:

```json
{
  "success": true,
  "data": [
    {
      "base": "Y",
      "createdBy": 1,
      "dateCreate": "2020-04-22T05:37:42.000Z",
      "id": 1,
      "modifiedBy": 1,
      "name": "BASE",
      "sort": 100,
      "timestampX": "2024-10-22T04:31:37.000Z",
      "xmlId": "BASE"
    },
    {
      "base": "N",
      "createdBy": 29,
      "dateCreate": "2021-04-20T12:56:47.000Z",
      "id": 3,
      "modifiedBy": 1,
      "name": "2base",
      "sort": 100,
      "timestampX": "2024-10-22T04:31:36.000Z",
      "xmlId": null
    }
  ],
  "meta": {
    "total": 5,
    "hasMore": true
  }
}
```

The numbers in the example come from one specific account. On yours they will differ: detect the base type by `base: "Y"`, not by the value of `id`.

## Error response example

400 — filtering by a field that does not exist:

```json
{
  "success": false,
  "error": {
    "code": "UNKNOWN_FILTER_FIELD",
    "message": "Unknown filter field 'nonExistentField' for entity 'catalog-price-types'. Available: id, name, base, xmlId, sort, createdBy, modifiedBy, dateCreate, timestampX"
  }
}
```

## Errors

| HTTP | Code | Description |
|------|-----|---------|
| 400 | `UNKNOWN_FILTER_FIELD` | Filtering by a field a price type does not have. The message lists the available fields |
| 400 | `UNKNOWN_SORT_FIELD` | Sorting by a field a price type does not have |
| 422 | `BITRIX_ERROR` | Bitrix24 refused to read price types: the key owner has no portal administrator rights |
| 403 | `SCOPE_DENIED` | The API key does not carry the `catalog` scope |
| 401 | `MISSING_API_KEY` | The `X-Api-Key` header is missing |
| 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](/docs/errors).

## Known specifics

**There is exactly one base price type.** The filter `?filter[base]=Y` returns a single record — its `id` is the `catalogGroupId` of the base price for [`POST /v1/catalog-prices`](/docs/entities/catalog-prices).

**The method requires administrator rights.** The `catalog` scope is not enough: Bitrix24 returns price types only to a key whose owner has the Bitrix24 account administrator role. Otherwise a `422 BITRIX_ERROR` arrives with a Bitrix24 message about insufficient rights.

**Paging through `offset` is supported.** Vibecode returns the requested window `[offset, offset + limit)`: `meta.total` is the exact number of records matching the filter, `meta.hasMore` tells whether records exist beyond the window.

**When to use search instead of list:** for conditions over several fields, [`POST /v1/catalog-price-types/search`](./search.md) is more convenient — the filter travels in the request body.

## See also

- [Get a price type](/docs/entities/catalog-price-types/get)
- [Search price types](/docs/entities/catalog-price-types/search)
- [Price type fields](/docs/entities/catalog-price-types/fields)
- [Catalog prices](/docs/entities/catalog-prices)
- [Filtering syntax](/docs/filtering)
- [API reference](/docs/api-reference)