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

Remove the paid mark from a CRM payment

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

Removes the paid mark from a CRM payment, for example before deleting it: a payment marked as paid cannot be deleted. Removing the mark, like setting it, can trigger Bitrix24 account automation rules.

Parameters

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

Send no request body or send {}.

Examples

curl — personal key

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/crm-payments/565/unpay" \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth application

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/crm-payments/565/unpay" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/crm-payments/565/unpay', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
  },
})

const { data } = await res.json()
console.log(`Payment ${data.accountNumber}, paid mark: ${data.paid}`)

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/crm-payments/565/unpay', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

const { data } = await res.json()

Response fields

Returns the payment after the mark is removed.

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 sequence number, separated by /
Fielddata.paid Typestring DescriptionN — the mark is removed
Fielddata.datePaid Typestring | null DescriptionTime the payment was last marked as paid, ISO 8601 with a time zone offset. Removing the mark does not clear it
Fielddata.empPaidId Typenumber | null DescriptionID of the employee who last marked the payment as paid. Removing the mark does not clear it. List: GET /v1/users
Fielddata.paySystemId Typenumber DescriptionPayment system ID. List: GET /v1/pay-systems
Fielddata.sum Typenumber DescriptionPayment amount
Fielddata.currency Typestring DescriptionCurrency code. List: GET /v1/currencies
Fielddata.paySystemName Typestring DescriptionPayment system name
Fieldmeta.readbackUnavailable Typeboolean DescriptionPresent only as true when the mark is removed but the payment could not be read back. In that case data contains only id. You do not need to repeat the request — get the payment by this id

Response example

JSON 
{
  "success": true,
  "data": {
    "id": 565,
    "accountNumber": "1029/2",
    "paid": "N",
    "datePaid": "2026-10-05T09:29:34+00:00",
    "empPaidId": 1317,
    "paySystemId": 3,
    "sum": 0,
    "currency": "USD",
    "paySystemName": "Bank transfer (Contacts)"
  }
}

Error response example

404 — no payment with this ID:

JSON 
{
  "success": false,
  "error": {
    "code": "ENTITY_NOT_FOUND",
    "message": "Payment has not been found"
  }
}

Errors

HTTP Code Description
HTTP404 CodeENTITY_NOT_FOUND DescriptionNo payment with this id
HTTP400 CodeREADONLY_FIELD DescriptionThe request body is not empty
HTTP400 CodeFST_ERR_CTP_EMPTY_JSON_BODY DescriptionThe Content-Type: application/json header is sent with an empty body. Send {} as the body or remove the header
HTTP400 CodeINVALID_ID Descriptionid is not a positive integer
HTTP422 CodeBITRIX_NO_EFFECT DescriptionBitrix24 did not confirm removing the mark
HTTP422 CodeBITRIX_ERROR DescriptionBitrix24 rejected the request; the reason is in error.message
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 sent

Full list of common API errors — Errors.

Known specifics

Removing the mark again does not change the payment. Calling it for a payment without the mark returns 200 with the same payment.

See also