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

Change the quantity in a CRM payment line item

PATCH /v1/crm-payments/:id/products/:itemId

Sets a new quantity for a CRM payment line item. The payment amount is recalculated immediately.

The field is 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
ParameteritemId (path) Typenumber Requiredyes DescriptionPayment line item ID, not the deal product row ID. List: GET /v1/crm-payments/:id/products, field data[].id

Request fields (body)

Field Type Required Description
Fieldquantity Typenumber Requiredyes DescriptionNew quantity, a positive integer. No more than the line item's current quantity plus the row's remainder in the available product rows

Examples

curl — personal key

Terminal 
curl -X PATCH "https://vibecode.bitrix24.com/v1/crm-payments/573/products/445" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "quantity": 3 }'

curl — OAuth application

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

JavaScript — personal key

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

const { data } = await res.json()
console.log(`Payment ${data.accountNumber} amount: ${data.sum} ${data.currency}`)

JavaScript — OAuth application

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

const { data } = await res.json()

Response fields

The response is the payment after the change, not the line item. The updated line item quantity is in GET /v1/crm-payments/:id/products.

Field Type Description
Fieldsuccess Typeboolean Descriptiontrue on success
Fielddata Typeobject DescriptionPayment object. Key payment fields are on the CRM payments page
Fielddata.id Typenumber DescriptionPayment ID
Fielddata.accountNumber Typestring DescriptionPayment number: the linked order number and the payment's sequence number separated by /, for example 1035/1
Fielddata.paid Typestring DescriptionPaid mark: Y — paid, N — not paid
Fielddata.datePaid Typestring | null DescriptionTime of the last "paid" mark, ISO 8601 with a time zone offset. null if the payment was never marked
Fielddata.empPaidId Typenumber | null DescriptionID of the employee who last marked the payment as paid. List: GET /v1/users
Fielddata.paySystemId Typenumber DescriptionPayment system ID. List: GET /v1/pay-systems
Fielddata.sum Typenumber DescriptionPayment amount including the new quantity
Fielddata.currency Typestring DescriptionCurrency code. List: GET /v1/currencies
Fielddata.paySystemName Typestring DescriptionPayment system name
Fieldmeta.readbackUnavailable Typeboolean DescriptionReturned only with the value true when the quantity was changed but the payment could not be read back. In that case data contains only id. Do not repeat the change. Check the line items via GET /v1/crm-payments/:id/products

Response example

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

Error response example

404 — no line item with this itemId in this payment:

JSON 
{
  "success": false,
  "error": {
    "code": "ENTITY_NOT_FOUND",
    "message": "Payable item has not been found in this payment."
  }
}

Errors

HTTP Code Description
HTTP400 CodeMISSING_REQUIRED_FIELDS DescriptionThe body is missing and there is no Content-Type header, quantity is not provided, or the value is not a positive integer, for example 0 or 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 quantity, or the body is not a JSON object, for example null or an array
HTTP400 CodeINVALID_ID Descriptionid or itemId is not a positive integer
HTTP404 CodeENTITY_NOT_FOUND DescriptionNo line item with this itemId in this payment, message Payable item has not been found in this payment.
HTTP404 CodeENTITY_NOT_FOUND DescriptionNo payment with this id, message Payment has not been found
HTTP422 CodeBITRIX_ERROR Descriptionquantity exceeds the line item's current quantity plus 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 DescriptionBitrix24 did not confirm the quantity change
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

Reducing the quantity returns it to the row's remainder. After a line item is reduced from 2 to 1 unit, the row's quantity in the available product rows increases by 1.

See also