Invoices

CRM invoice management: create, retrieve, update, delete, filter. An invoice is a request for payment: it carries the payer, the seller company and the product rows, and its stage shows where the invoice stands in the issue-and-payment cycle.

Bitrix24 API: crm.item.*, entityTypeId equals 31 Scope: crm

Create invoice

POST /v1/invoices

Creates a new invoice in CRM.

Request fields (body)

Field	Type	Description
`title`	string	Invoice title. If omitted, `Invoice #<id>` is used
`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	Invoice 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

No fields are required: any single field is enough to create an invoice, and the rest are filled with the Bitrix24 account defaults. An empty body is rejected with 400 EMPTY_CREATE_BODY.

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": 1500,
    "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": 1500,
    "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: 1500,
    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: 1500,
    currencyId: 'USD',
    assignedById: 1,
  }),
})

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

Response fields

Field	Type	Description
`success`	boolean	Always `true` on success
`data`	object	The created invoice in full, including the `ufCrm_*` user fields. For every field see Invoice fields

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 portal domain. Access is restricted by the employee's permissions in Bitrix24.

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:N",
    "categoryId": 5,
    "contactId": 42,
    "companyId": 15,
    "opportunity": 1500,
    "currencyId": "USD",
    "assignedById": 1,
    "createdBy": 1,
    "createdTime": "2026-08-25T08:13:37.000Z",
    "updatedTime": "2026-08-25T08:13:37.000Z"
  }
}

Error response example

400 — the request body is empty: