# Deals

CRM deal management: create, retrieve, update, delete, filter.

Bitrix24 API: `crm.item.*`
Scope: `crm`

## Operations

- [Create deal](./deals/create.md) — `POST /v1/deals`
- [List deals](./deals/list.md) — `GET /v1/deals`
- [Get deal](./deals/get.md) — `GET /v1/deals/:id`
- [Update deal](./deals/update.md) — `PATCH /v1/deals/:id`
- [Delete deal](./deals/delete.md) — `DELETE /v1/deals/:id`
- [Move to another stage](./deals/move.md) — `POST /v1/deals/:id/move`
- [Search deals](./deals/search.md) — `POST /v1/deals/search`
- [Deal fields](./deals/fields.md) — `GET /v1/deals/fields`
- [Aggregate deals](./deals/aggregate.md) — `POST /v1/deals/aggregate`
- [Get products](./deals/products-get.md) — `GET /v1/deals/:id/products`
- [Set products](./deals/products-set.md) — `PUT /v1/deals/:id/products`
- [Add product](./deals/products-add.md) — `POST /v1/deals/:id/products`
- [Delete product](./deals/products-delete.md) — `DELETE /v1/deals/:id/products/:rowId`
- [Get product](./deals/products-get-single.md) — `GET /v1/deals/:id/products/:rowId`
- [Update product](./deals/products-update.md) — `PATCH /v1/deals/:id/products/:rowId`
- [Product fields](./deals/products-fields.md) — `GET /v1/deals/:id/products/fields`
- [List deal contacts](./deals/contacts-list.md) — `GET /v1/deals/:id/contacts`
- [Replace deal contacts](./deals/contacts-set.md) — `PUT /v1/deals/:id/contacts`
- [Link a contact to a deal](./deals/contacts-create.md) — `POST /v1/deals/:id/contacts`
- [Unlink a contact from a deal](./deals/contacts-delete-delete.md) — `DELETE /v1/deals/:id/contacts/:relatedId`
- [Unlink all contacts from a deal](./deals/contacts-delete.md) — `DELETE /v1/deals/:id/contacts`
- [Import records](../import.md) — `POST /v1/deals/import`

## Key fields

| Field | Description |
|------|----------|
| `id` | Deal ID. Source: [List deals](./deals/list.md) |
| `title` | Deal title |
| `stageId` | Funnel stage. Source: [List of dictionaries](./statuses/list.md) with `entityId=DEAL_STAGE` for the main funnel or `entityId=DEAL_STAGE_{categoryId}` for any other funnel |
| `categoryId` | Funnel ID. Source: [List pipelines](./deal-categories/list.md) |
| `amount` | Deal amount |
| `currency` | Amount currency. Source: [List currencies](./currencies/list.md) |
| `companyId` | Linked company. Source: [List companies](./companies/list.md) |
| `assignedById` | Assignee. Source: [List employees](./users/list.md) |

Full field list — [Deal fields](./deals/fields.md).

## What to know before you start

1. On create and update, pass fields at the JSON root, without a `fields` wrapper. The format is described on the [Create deal](./deals/create.md) and [Update deal](./deals/update.md) pages.
2. The funnel in `categoryId` defines the set of `stageId` stages. For the main funnel with `categoryId=0`, use the `DEAL_STAGE` dictionary; for the rest, `DEAL_STAGE_{categoryId}`. Take the stage value from the `statusId` field of a record returned by [List of dictionaries](./statuses/list.md).
3. Deal products and contacts are managed by separate operations: [Get products](./deals/products-get.md) and [List deal contacts](./deals/contacts-list.md).
4. [CRM payments](./crm-payments.md) and [deliveries](./crm-deliveries.md) use `entityTypeId=2` and the deal ID.
5. [Recurring deals](./recurring-deals.md) create deals from templates on a schedule.

## Typical scenario

1. Pick a funnel with [List pipelines](./deal-categories/list.md).
2. Get its stages with [List of dictionaries](./statuses/list.md) with the `entityId` you need.
3. [Create deal](./deals/create.md), passing `title`, `categoryId`, and the selected `stageId`.
4. Set line items with [Set products](./deals/products-set.md).
5. As work progresses, [move the deal to another stage](./deals/move.md).

## Limits

| Limit | Value |
|-------|----------|
| Maximum records per request | 5000 (`limit ≤ 5000`) |
| Automatic pagination | enabled when `limit > 50` |
| `offset` on large result sets | `limit ≤ 500` recommended when `offset ≥ 2500` |
| Batch requests | up to 50 operations in [Batch calls](/docs/batch) |
| Request rate | shared across the Vibecode API — see [Limits and optimization](/docs/optimization) |

## See also

- [Sales pipelines](./deal-categories.md)
- [CRM dictionaries](./statuses.md)
- [CRM payments](./crm-payments.md)
- [CRM deliveries](./crm-deliveries.md)
- [Recurring deals](./recurring-deals.md)
- [Import records](../import.md)