# CRM payments

Payments of a CRM item, such as a deal: creating a payment, filling it with products from the item's product rows, setting the "paid" mark and removing it.

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

## Operations

- [Create a CRM payment](./crm-payments/create.md) — `POST /v1/crm-payments`
- [List CRM payments](./crm-payments/list.md) — `GET /v1/crm-payments`
- [Get a CRM payment](./crm-payments/get.md) — `GET /v1/crm-payments/:id`
- [Update a CRM payment](./crm-payments/update.md) — `PATCH /v1/crm-payments/:id`
- [Delete a CRM payment](./crm-payments/delete.md) — `DELETE /v1/crm-payments/:id`
- [Set the "paid" mark](./crm-payments/pay.md) — `POST /v1/crm-payments/:id/pay`
- [Remove the "paid" mark](./crm-payments/unpay.md) — `POST /v1/crm-payments/:id/unpay`
- [Available product rows](./crm-payments/available-products.md) — `GET /v1/crm-payments/available-products`
- [List payment line items](./crm-payments/products-list.md) — `GET /v1/crm-payments/:id/products`
- [Add a line item](./crm-payments/products-add.md) — `POST /v1/crm-payments/:id/products`
- [Delete a line item](./crm-payments/products-delete.md) — `DELETE /v1/crm-payments/:id/products/:itemId`
- [Change the quantity in a line item](./crm-payments/products-update.md) — `PATCH /v1/crm-payments/:id/products/:itemId`

## Key fields

| Field | Type | Description |
|------|-----|---------|
| `id` | number | Payment ID. The same payment has the same ID in the [order payments](./payments.md) section |
| `accountNumber` | string | Payment number: the linked order number and the payment's sequence number separated by `/`, for example `1035/1` |
| `paid` | string | Payment mark: `Y` — paid, `N` — not paid |
| `sum` | number | Payment amount. Made up of the line items and cannot be set directly |
| `paySystemId` | number | Payment system ID. List: [`GET /v1/pay-systems`](/docs/entities/pay-systems/list) |
| `entityTypeId`, `entityId` | number | The CRM item the payment belongs to. For a deal, `entityTypeId` is `2` and `entityId` is the ID from [`GET /v1/deals`](/docs/entities/deals/list) |
| `rowId` | number | ID of the item's product row when adding a line item. List: [`GET /v1/crm-payments/available-products`](./crm-payments/available-products.md) |
| `itemId` | number | Payment line item ID for changing and deleting. List: [`GET /v1/crm-payments/:id/products`](./crm-payments/products-list.md) |

A payment has few fields, and there is no separate field schema method. The full set is in [`GET /v1/crm-payments/:id`](./crm-payments/get.md).

## Before you start

1. **A payment always belongs to a CRM item.** Listing payments, creating a payment and fetching available product rows require `entityTypeId` and `entityId`. When a payment is created for a deal, the deal gets a linked order. You do not need to create it separately.
2. **The amount is made up of line items.** A new payment is created with the amount `0`. A line item is a part of the item's product row in a whole-number quantity, and each product row goes into a payment as a single line item. The quantity added to payments is taken from the row's remainder and returns to it when the line item is deleted or its quantity is reduced.
3. **The same ID appears in order payments.** A CRM payment is also visible in [`GET /v1/payments/:id`](./payments/get.md) with the `sale` scope, but in a different format: there `paid` is `true` or `false`, and the order ID is in `orderId`. For payments of an existing order that is not linked to a CRM item, use [order payments](./payments.md).
4. **The "paid" mark does not transfer money.** [`POST /v1/crm-payments/:id/pay`](./crm-payments/pay.md) only sets the mark and can trigger automation, an email or an online receipt. A payment marked as paid cannot be deleted. Remove the mark first via [`POST /v1/crm-payments/:id/unpay`](./crm-payments/unpay.md).
5. **A write is confirmed by the reread payment.** The response to creating and updating a payment, setting and removing the mark, adding a line item and changing its quantity contains the payment read after the write. If it could not be reread, the response carries `meta.readbackUnavailable: true`, and `data` contains only the ID: of the payment or, when adding a line item, of the line item and the payment. The write has already completed. You do not need to repeat the call. Check the result by ID instead.

## Typical scenario

1. Find the deal's product rows that have a remaining quantity: [`GET /v1/crm-payments/available-products?entityTypeId=2&entityId=:dealId`](./crm-payments/available-products.md).
2. Create a payment for the deal: [`POST /v1/crm-payments`](./crm-payments/create.md) with `entityTypeId` and `entityId`.
3. Add line items: [`POST /v1/crm-payments/:id/products`](./crm-payments/products-add.md) with the row's `rowId` and an integer `quantity`.
4. Check the amount: [`GET /v1/crm-payments/:id`](./crm-payments/get.md).
5. When the money is received, set the mark: [`POST /v1/crm-payments/:id/pay`](./crm-payments/pay.md).

## Limits

| Limit | Value |
|-------|----------|
| List pagination | none — the item's payments and the payment's line items all arrive in one call |
| `filter` and `order` in the payment list | payment fields only, exact value match |
| Quantity in a line item | positive integer. When adding, no more than the product row's remainder. When changing, no more than the line item's current quantity plus the row's remainder |
| Line items of one product row in a payment | one |
| Batch calls | not supported: [`POST /v1/batch`](/docs/batch) returns `UNKNOWN_ENTITY` for `crm-payments`, so call the section's endpoints one at a time |
| Request rate | shared across the Vibecode API — see [Limits and optimization](/docs/optimization) |

## See also

- [Order payments](./payments.md)
- [Deals](./deals.md)
- [Payment systems](./pay-systems.md)
- [Basket items](./basket-items.md)
- [Entity reference](/docs/entity-api)