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.

Request parameters

Parameter Type Description
id number Invoice ID (in the URL)

Request fields (body)

Parameter 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 the administrator
contactId number Payer contact ID
companyId number Payer company ID
opportunity number Amount
currencyId string Currency. List: GET /v1/currencies
assignedById number Assignee. List: GET /v1/users
comments string Comment

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/891 \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "opportunity": 200000,
    "stageId": "DT31_5:WON"
  }'

curl — OAuth application

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

JavaScript — personal key

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

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/891', {
  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:WON',
  }),
})

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

Response fields

Field Type Description
id number Invoice ID
title string Title
stageId string Stage
opportunity number Amount
currencyId string Currency
assignedById number Assignee
updatedTime datetime Modification date

The response contains all invoice fields after the update.

Response example

JSON 
{
  "success": true,
  "data": {
    "id": 891,
    "title": "Invoice for services",
    "stageId": "DT31_5:WON",
    "categoryId": 5,
    "contactId": 42,
    "companyId": 15,
    "opportunity": 200000,
    "currencyId": "USD",
    "assignedById": 1,
    "createdBy": 1,
    "createdTime": "2026-04-15T14:30:00+00:00",
    "updatedTime": "2026-04-15T15:10:00+00:00"
  }
}

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
403 SCOPE_DENIED API key lacks the crm scope
401 TOKEN_MISSING API key has no configured tokens
400 INVALID_REQUEST Invalid fields

Full list of common API errors — Errors.

See also