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
id (path) number yes Payment 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
success boolean true on success
data object Payment object. Key payment fields are on the CRM payments page
data.id number Payment ID
data.accountNumber string Payment number: the linked order number and the payment sequence number, separated by /
data.paid string N — the mark is removed
data.datePaid string | null Time the payment was last marked as paid, ISO 8601 with a time zone offset. Removing the mark does not clear it
data.empPaidId number | null ID of the employee who last marked the payment as paid. Removing the mark does not clear it. List: GET /v1/users
data.paySystemId number Payment system ID. List: GET /v1/pay-systems
data.sum number Payment amount
data.currency string Currency code. List: GET /v1/currencies
data.paySystemName string Payment system name
meta.readbackUnavailable boolean Present 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
404 ENTITY_NOT_FOUND No payment with this id
400 READONLY_FIELD The request body is not empty
400 FST_ERR_CTP_EMPTY_JSON_BODY The Content-Type: application/json header is sent with an empty body. Send {} as the body or remove the header
400 INVALID_ID id is not a positive integer
422 BITRIX_NO_EFFECT Bitrix24 did not confirm removing the mark
422 BITRIX_ERROR Bitrix24 rejected the request; the reason is in error.message
403 BITRIX_ACCESS_DENIED The key's user has no access to the CRM item or the payment in Bitrix24
403 WRITE_BLOCKED_READONLY_KEY The key is not allowed to write
403 SCOPE_DENIED The API key does not have the crm scope
401 TOKEN_MISSING The API key has no configured tokens
401 MISSING_API_KEY X-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