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 Required Description
Parameterid (path) Typenumber Requiredyes DescriptionInvoice ID

Request fields (body)

Field Type Description
Fieldtitle Typestring DescriptionInvoice title
FieldstageId Typestring DescriptionStage. 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
FieldcategoryId Typenumber DescriptionPipeline ID
FieldcontactId Typenumber DescriptionPayer contact ID. Lookup: GET /v1/contacts
FieldcompanyId Typenumber DescriptionPayer company ID. Lookup: GET /v1/companies
FieldmycompanyId Typenumber DescriptionID of your own company (the seller) issuing the invoice. Lookup: GET /v1/companies
Fieldopportunity Typenumber DescriptionAmount
FieldcurrencyId Typestring DescriptionCurrency. List: GET /v1/currencies
FieldassignedById Typenumber DescriptionAssignee. List: GET /v1/users
Fieldbegindate Typedatetime DescriptionInvoice start date
Fieldclosedate Typedatetime DescriptionInvoice payment date
FieldaccountNumber Typestring DescriptionPrintable invoice number
Fieldcomments Typestring DescriptionComment

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
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata Typeobject DescriptionThe 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
HTTP404 CodeENTITY_NOT_FOUND DescriptionInvoice with the specified ID not found
HTTP400 CodeEMPTY_UPDATE_BODY DescriptionThe request body is empty — at least one field is needed
HTTP400 CodeREADONLY_FIELD DescriptionThe body carries a read-only field — id, createdBy, createdTime or any other field marked so in GET /v1/invoices/fields
HTTP400 CodeINVALID_PARAMS DescriptionThe id in the URL is not a non-negative integer
HTTP403 CodeSCOPE_DENIED DescriptionAPI key lacks the crm scope
HTTP401 CodeTOKEN_MISSING DescriptionAPI key has no configured tokens

Full list of common API errors — Errors.

Known specifics

An unknown scalar field name is never stored. It 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. An object under fields is rejected with 400 NESTED_FIELDS_ENVELOPE before the update — pass invoice fields at the JSON root. A typo in a field name cannot be caught by the response code — check names against the GET /v1/invoices/fields schema.

See also