For AI agents: markdown of this page — /docs-content-en/entities/crm-payments/products-add.md documentation index — /llms.txt

Add a line item to a CRM payment

POST /v1/crm-payments/:id/products

Adds a line item to a CRM payment: the specified quantity taken from a product row of a CRM item, such as a deal. The payment amount is recalculated immediately.

Fields are passed flat at the JSON root, without a fields wrapper.

Parameters

Parameter Type Required Description
Parameterid (path) Typenumber Requiredyes DescriptionPayment ID. Payments of a CRM item: GET /v1/crm-payments

Request fields (body)

Field Type Required Description
FieldrowId Typenumber Requiredyes DescriptionID of the CRM item's product row. List: GET /v1/crm-payments/available-products, field productRows[].id
Fieldquantity Typenumber Requiredyes DescriptionQuantity, a positive integer. Must not exceed the row's remainder, which is the productRows[].quantity field in the available product rows

Examples

curl — personal key

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/crm-payments/573/products" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "rowId": 2357, "quantity": 2 }'

curl — OAuth application

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/crm-payments/573/products" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "rowId": 2357, "quantity": 2 }'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/crm-payments/573/products', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ rowId: 2357, quantity: 2 }),
})

const { data } = await res.json()
console.log('Line item ID:', data.id, 'payment amount:', data.payment.sum)

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/crm-payments/573/products', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ rowId: 2357, quantity: 2 }),
})

const { data } = await res.json()

Response fields

A successful response returns HTTP status 201.

Field Type Description
Fieldsuccess Typeboolean Descriptiontrue on success
Fielddata.id Typenumber DescriptionID of the created payment line item. Passed as itemId to PATCH and DELETE /v1/crm-payments/:id/products/:itemId
Fielddata.payment Typeobject DescriptionThe payment after the line item is added, with the same fields as in GET /v1/crm-payments/:id
Fielddata.payment.id Typenumber DescriptionPayment ID
Fielddata.payment.sum Typenumber DescriptionPayment amount including the new line item
Fieldmeta.readbackUnavailable Typeboolean DescriptionReturned only with the value true when the line item was added but the payment could not be read back. In that case data.payment contains only id. Do not add the line item again. Check the line items via GET /v1/crm-payments/:id/products

Response example

JSON 
{
  "success": true,
  "data": {
    "id": 445,
    "payment": {
      "id": 573,
      "accountNumber": "1035/1",
      "paid": "N",
      "datePaid": null,
      "empPaidId": null,
      "paySystemId": 19,
      "sum": 3000,
      "currency": "USD",
      "paySystemName": "Card payment"
    }
  }
}

Error response example

422 — quantity exceeds the product row's remainder:

JSON 
{
  "success": false,
  "error": {
    "code": "BITRIX_ERROR",
    "message": "Not enough product to add to the payment",
    "b24Code": "0"
  }
}

Errors

HTTP Code Description
HTTP400 CodeMISSING_REQUIRED_FIELDS DescriptionThe body is missing and there is no Content-Type header, rowId or quantity is not provided, or the value is not a positive integer, for example 1.5
HTTP400 CodeFST_ERR_CTP_EMPTY_JSON_BODY DescriptionThe Content-Type: application/json header is sent with an empty body
HTTP400 CodeREADONLY_FIELD DescriptionThe body contains a field other than rowId and quantity, or the body is not a JSON object, for example null or an array
HTTP400 CodeINVALID_ID Descriptionid is not a positive integer
HTTP404 CodeENTITY_NOT_FOUND DescriptionNo payment with this id, message Payment has not been found
HTTP404 CodeENTITY_NOT_FOUND DescriptionThe row lookup confirmed that no product row has this rowId; message Product row was not found. in every portal language
HTTP404 CodeENTITY_NOT_FOUND DescriptionThe product row exists, but this payment cannot pay for it; message Product was not found. on en/de/kz portals, or a localized Russian message on ru portals (shown in the Russian documentation)
HTTP422 CodeBITRIX_ERROR Descriptionquantity exceeds the row's remainder, message Not enough product to add to the payment
HTTP422 CodeBITRIX_ERROR DescriptionBitrix24 rejected the request. The reason is in error.message
HTTP422 CodeBITRIX_NO_EFFECT DescriptionThe line item was not created, for example because a row with this rowId is already in this payment. The existing line item does not change. To change its quantity, use PATCH /v1/crm-payments/:id/products/:itemId
HTTP403 CodeBITRIX_ACCESS_DENIED DescriptionThe key's user has no access to the CRM item or the payment in Bitrix24
HTTP403 CodeWRITE_BLOCKED_READONLY_KEY DescriptionThe key is not allowed to write
HTTP403 CodeSCOPE_DENIED DescriptionThe API key does not have the crm scope
HTTP401 CodeTOKEN_MISSING DescriptionThe API key has no configured tokens
HTTP401 CodeMISSING_API_KEY DescriptionX-Api-Key is not provided

Full list of common API errors — Errors.

Known specifics

The added quantity is taken from the row's remainder. After 2 units are added from a row of 3 units, the quantity of this row in the available product rows becomes 1.

See also