# Payer types

A list of payer types for an online store. The type ID is passed in the `personTypeId` field of an order or order property.

Types with the codes `CRM_CONTACT` and `CRM_COMPANY` are protected from deletion. Include `name` whenever you update a type, even if you are only changing other fields.

Bitrix24 API: `sale.persontype.*`
Scope: `sale`

## Operations

- [Create a payer type](./person-types/create.md) — `POST /v1/person-types`
- [List payer types](./person-types/list.md) — `GET /v1/person-types`
- [Get a payer type](./person-types/get.md) — `GET /v1/person-types/:id`
- [Update a payer type](./person-types/update.md) — `PATCH /v1/person-types/:id`
- [Delete a payer type](./person-types/delete.md) — `DELETE /v1/person-types/:id`
- [Search payer types](./person-types/search.md) — `POST /v1/person-types/search`
- [Payer type fields](./person-types/fields.md) — `GET /v1/person-types/fields`
- [Aggregate payer types](./person-types/aggregate.md) — `POST /v1/person-types/aggregate`

## Key fields

| Field | Type | Description |
|-------|------|-------------|
| `id` | number | Payer type ID. List: [`GET /v1/person-types`](./person-types/list.md) |
| `name` | string | Name. Include it when creating a type and in every update |
| `code` | string \| null | Unique code. `CRM_CONTACT` and `CRM_COMPANY` identify system types |
| `active` | boolean | Whether the type is active |
| `sort` | number | Sort order |
| `xmlId` | string \| null | External ID |

For the full field list, see [`GET /v1/person-types/fields`](./person-types/fields.md).

## Before you start

1. **Choose a payer type for the order from the list.** The `personTypeId` field is used in [orders](/docs/entities/orders) and [order properties](/docs/entities/order-properties).
2. **The code must be unique.** Creating or updating a type with a `code` that is already in use returns `422 BITRIX_ERROR`.
3. **Every update requires the name.** To keep the name, read it with [`GET /v1/person-types/:id`](./person-types/get.md) and include it in [`PATCH`](./person-types/update.md) alongside the fields to change. Without `name`, Bitrix24 returns `422 BITRIX_ERROR`.
4. **System types cannot be deleted.** [`DELETE`](./person-types/delete.md) for `code: "CRM_CONTACT"` or `code: "CRM_COMPANY"` returns `422 BITRIX_ERROR` with `b24Code: "200750000003"`. To deactivate your own type, send its name and `active: false` in [`PATCH`](./person-types/update.md).
5. **The assigned site is separate from the returned data.** The `lid` field appears in the [field metadata](./person-types/fields.md), but is absent from response objects. Writing `id` or `lid` returns `400 READONLY_FIELD`.

## Typical workflow

1. Check existing types: [`GET /v1/person-types`](./person-types/list.md) or [`POST /v1/person-types/search`](./person-types/search.md).
2. Create your own type with a name and unique code: [`POST /v1/person-types`](./person-types/create.md).
3. Pass the returned `id` in `personTypeId` when [creating an order](/docs/entities/orders/create) or [creating an order property](/docs/entities/order-properties/create).
4. To update the type, send its `name` and the new values: [`PATCH /v1/person-types/:id`](./person-types/update.md).
5. When your type is no longer needed, deactivate it with `active: false`. To delete it, use [`DELETE /v1/person-types/:id`](./person-types/delete.md).

## Limits

| Limit | Value |
|-------|-------|
| Records per list or search request | Up to 5000 (`limit`), 50 by default. Request the following records with `offset` |
| Aggregation | Up to 5 expressions: `count`, `sum`, `avg`, `min`, `max`. Up to 5000 records are read for calculations and grouping |
| Grouping | By `active` and `code`, up to 5 dimensions. `groupLimit` ranges from 1 to 1000 |
| Batch writes | `create`, `update`, `delete` — see [Batch](/docs/batch) |
| Request rate | Shared across the Vibecode API — see [Limits and optimization](/docs/optimization) |

## See also

- [Orders](/docs/entities/orders)
- [Order properties](/docs/entities/order-properties)
- [Entity API](/docs/entity-api)
- [Batch](/docs/batch)