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

Invoices

CRM invoice management: create, retrieve, update, delete, filter.

Bitrix24 API: crm.item.* (SPA entity, entityTypeId = 31) Scope: crm

Create invoice

POST /v1/invoices

Creates a new invoice in CRM.

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
categoryId number Pipeline ID
contactId number Payer contact ID. Lookup: GET /v1/contacts
companyId number Payer company ID. Lookup: GET /v1/companies
mycompanyId number Own company ID
opportunity number Invoice 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 POST https://vibecode.bitrix24.com/v1/invoices \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Invoice for services",
    "stageId": "DT31_5:N",
    "contactId": 42,
    "companyId": 15,
    "opportunity": 150000,
    "currencyId": "USD",
    "assignedById": 1
  }'

curl — OAuth application

Terminal 
curl -X POST https://vibecode.bitrix24.com/v1/invoices \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Invoice for services",
    "stageId": "DT31_5:N",
    "contactId": 42,
    "companyId": 15,
    "opportunity": 150000,
    "currencyId": "USD",
    "assignedById": 1
  }'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/invoices', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    title: 'Invoice for services',
    stageId: 'DT31_5:N',
    contactId: 42,
    companyId: 15,
    opportunity: 150000,
    currencyId: 'USD',
    assignedById: 1,
  }),
})

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

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/invoices', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    title: 'Invoice for services',
    stageId: 'DT31_5:N',
    contactId: 42,
    companyId: 15,
    opportunity: 150000,
    currencyId: 'USD',
    assignedById: 1,
  }),
})

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

Response fields

Field Type Description
id number ID of the created invoice
title string Title
stageId string Stage
contactId number Contact ID
companyId number Company ID
opportunity number Amount
currencyId string Currency
assignedById number Assignee
createdBy number Creator
createdTime datetime Creation date
updatedTime datetime Modification date

The response contains all invoice fields, including user fields (ufCrm_*).

The invoice card URL in Bitrix24 is built from id:

https://<portal>.bitrix24.com/crm/type/31/details/<id>/

31 — the entityTypeId of the smart invoice in Bitrix24. <portal> — the Bitrix24 account domain. Access is restricted by the employee's permissions in Bitrix24.

Response example

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

Error response example

403 — no scope:

JSON 
{
  "success": false,
  "error": {
    "code": "SCOPE_DENIED",
    "message": "This endpoint requires 'crm' scope"
  }
}

Errors

HTTP Code Description
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