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

Update invoice

PATCH /v1/invoices/:id

Updates invoice fields. Pass only the fields being changed.

Parameters

Parameter Type Req. Description
id (path) number yes Invoice ID

Request fields (body)

Field Type Description
title string Invoice title
stageId string Stage. Format: DT31_{categoryId}:{stage}. Stage list: GET /v1/statuses?filter[entityId]=SMART_INVOICE_STAGE_{categoryId} — categoryId depends on the Bitrix24 account. To find it: GET /v1/invoices?limit=1&select=categoryId or ask your Bitrix24 account administrator
categoryId number Pipeline ID
contactId number Payer contact ID. Lookup: GET /v1/contacts
companyId number Payer company ID. Lookup: GET /v1/companies
mycompanyId number ID of your own company (the seller) issuing the invoice. Lookup: GET /v1/companies
opportunity number Amount
currencyId string Currency. List: GET /v1/currencies
assignedById number Assignee. List: GET /v1/users
begindate datetime Invoice start date
closedate datetime Invoice payment date
accountNumber string Printable invoice number
comments string Comment

Pass only the fields being changed, but at least one: an empty body is rejected with 400 EMPTY_UPDATE_BODY.

Full list of fields: GET /v1/invoices/fields. User fields (ufCrm_*) are also accepted.

Examples

curl — personal key

Terminal 
curl -X PATCH https://vibecode.bitrix24.com/v1/invoices/129 \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "opportunity": 200000,
    "stageId": "DT31_5:P"
  }'

curl — OAuth application

Terminal 
curl -X PATCH https://vibecode.bitrix24.com/v1/invoices/129 \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "opportunity": 200000,
    "stageId": "DT31_5:P"
  }'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/invoices/129', {
  method: 'PATCH',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    opportunity: 200000,
    stageId: 'DT31_5:P',
  }),
})

const { success, data } = await res.json()
console.log('Updated:', data.id)

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/invoices/129', {
  method: 'PATCH',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    opportunity: 200000,
    stageId: 'DT31_5:P',
  }),
})

const { success, data } = await res.json()

Response fields

Field Type Description
success boolean Always true on success
data object The invoice in full after the update. For every field see Invoice fields

Response example

Key fields are shown. For the full record see Invoice fields.

JSON 
{
  "success": true,
  "data": {
    "id": 129,
    "title": "Invoice for services",
    "stageId": "DT31_5:P",
    "categoryId": 5,
    "contactId": 42,
    "companyId": 15,
    "opportunity": 200000,
    "currencyId": "USD",
    "assignedById": 1,
    "createdBy": 1,
    "createdTime": "2026-08-25T08:13:37.000Z",
    "updatedTime": "2026-08-25T08:13:56.000Z"
  }
}

Error response example

404 — invoice not found:

JSON 
{
  "success": false,
  "error": {
    "code": "ENTITY_NOT_FOUND",
    "message": "Item not found"
  }
}

Errors

HTTP Code Description
404 ENTITY_NOT_FOUND Invoice with the specified ID not found
400 EMPTY_UPDATE_BODY The request body is empty — at least one field is needed
400 READONLY_FIELD The body carries a read-only field — id, createdBy, createdTime or any other field marked so in GET /v1/invoices/fields
400 INVALID_PARAMS The id in the URL is not a non-negative integer
403 SCOPE_DENIED API key lacks the crm scope
401 TOKEN_MISSING API key has no configured tokens

Full list of common API errors — Errors.

Known specifics

A field name the invoice does not have is accepted but never stored. Such a field raises no error: the response comes back with 200, the other fields passed are written, and the unknown one simply does not reach the record. A typo in a field name cannot be caught by the response code — check names against the GET /v1/invoices/fields schema.

See also