## Price fields

`GET /v1/catalog-prices/fields`

Returns a reference of product-price fields with their types, read-only and nullable flags, plus the list of operations available in a batch request.

## Examples

### curl — personal key

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

### curl — OAuth app

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

const { success, data } = await res.json()
console.log('Fields:', Object.keys(data.fields).length)
```

### JavaScript — OAuth app

```javascript
const res = await fetch('https://vibecode.bitrix24.com/v1/catalog-prices/fields', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

const { success, data } = await res.json()
```

## Response fields

`data.fields` — an object whose key matches the field name, and whose value contains `type` (the field type), `readonly` (`true` — the field cannot be passed on create or update), `nullable` (present when the field can come back as `null`), `label` (a human-readable field name) and `description` (a short description). `label`/`description` are returned in English. `data.batch` — the list of operations accepted by a [batch request](/docs/batch).

| Field | Type | RO | Description |
|------|-----|:--:|---------|
| `id` | number | yes | Price record identifier |
| `catalogGroupId` | number | no | Price type. Base price is `1`. To see which price types are configured in your Bitrix24 account, check the `catalogGroupId` values in the [price list](./list.md) |
| `currency` | string | no | Price currency, e.g. `USD`. List: [`GET /v1/currencies`](/docs/entities/currencies) |
| `price` | number | no | Price value |
| `productId` | number | no | ID of the product the price belongs to. List: [`GET /v1/catalog-products`](/docs/entities/catalog-products) |
| `quantityFrom` | number \| null | no | Lower bound of the quantity range. `null` in responses when the price does not depend on quantity |
| `quantityTo` | number \| null | no | Upper bound of the quantity range. `null` in responses when the price does not depend on quantity |
| `priceScale` | number | yes | Price in the Bitrix24 account's base currency. Set by the system |
| `extraId` | number \| null | yes | Markup identifier (`catalog_extra`). Deprecated Bitrix24 field. Set by the system. `null` when no markup is assigned |
| `timestampX` | datetime | yes | Date and time the price record was last modified, in ISO 8601 format (UTC) |

| Field | Type | Description |
|------|-----|---------|
| `success` | boolean | Always `true` on success |
| `data.fields.<name>.type` | string | Field type: `number`, `string`, `datetime` |
| `data.fields.<name>.readonly` | boolean | `true` — the field is set by the system and is not accepted on creation or update |
| `data.fields.<name>.nullable` | boolean | `true` — the field can come back as `null`. The key is present only on such fields |
| `data.fields.<name>.label` | string | Human-readable field name |
| `data.fields.<name>.description` | string | Short field description |
| `data.batch` | string[] | Price operations available in a [batch request](/docs/batch): `create`, `update`, `delete` |

## Response example

```json
{
  "success": true,
  "data": {
    "fields": {
      "id": { "type": "number", "readonly": true, "label": "ID", "description": "Record identifier of the catalog price." },
      "catalogGroupId": { "type": "number", "readonly": false, "label": "Price type", "description": "Price type identifier; base price type is 1." },
      "currency": { "type": "string", "readonly": false, "label": "Currency", "description": "Currency code of the price." },
      "price": { "type": "number", "readonly": false, "label": "Price", "description": "Numeric value of the price." },
      "productId": { "type": "number", "readonly": false, "label": "Product", "description": "ID of the product this price belongs to." },
      "quantityFrom": { "type": "number", "readonly": false, "nullable": true, "label": "Quantity from", "description": "Lower bound of the quantity range." },
      "quantityTo": { "type": "number", "readonly": false, "nullable": true, "label": "Quantity to", "description": "Upper bound of the quantity range." },
      "priceScale": { "type": "number", "readonly": true, "label": "Base price", "description": "Price in the Bitrix24 account's base currency." },
      "extraId": { "type": "number", "readonly": true, "nullable": true, "label": "Markup ID", "description": "Markup identifier (catalog_extra)." },
      "timestampX": { "type": "datetime", "readonly": true, "label": "Modified at", "description": "Date and time the price was last modified." }
    },
    "batch": ["create", "update", "delete"]
  }
}
```

The system fields `priceScale`, `extraId`, and `timestampX` are set by Bitrix24 and are read-only — they cannot be passed on creation or update.

## Error response example

403 — no scope:

```json
{
  "success": false,
  "error": {
    "code": "SCOPE_DENIED",
    "message": "This endpoint requires 'catalog' scope"
  }
}
```

## Errors

| HTTP | Code | Description |
|------|-----|---------|
| 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).

## See also

- [List prices](/docs/entities/catalog-prices/list)
- [Create a price](/docs/entities/catalog-prices/create)
- [Search prices](/docs/entities/catalog-prices/search)
- [Catalog products](/docs/entities/catalog-products)
- [Entities reference](/docs/entities-index)