Invoices: Overview of Methods and Events
If you are developing integrations for Bitrix24 using AI tools (Codex, Claude Code, Cursor), connect to the MCP server so that the assistant can utilize the official REST documentation.
An invoice is the final stage of a deal. It is created when all discussions are complete and the terms of the agreement are agreed upon. Multiple invoices can be created for different products and services within a single deal.
An invoice can be generated from a template and sent to the client as a document. In the invoice detail form, you can:
- Manage the sales process of a product or service
- Track the stages of working with the invoice
- Accept online payments
Invoices are a separate CRM object type with the identifier entityTypeId = 31. Work with them using the universal crm.item.* methods and pass entityTypeId = 31 in every call.
The crm.item.* methods work only with new-type invoices entityTypeId = 31. For old-type invoices entityTypeId = 5, they return the ENTITY_TYPE_NOT_SUPPORTED error.
Quick navigation: all methods and events
User documentation: New invoices in CRM
Getting Started
- Retrieve the list of available invoice fields using the crm.item.fields method with
entityTypeId = 31. - Create an invoice using the crm.item.add method. Link it to a deal through
parentId2and specify the client in thecompanyIdandcontactIdsfields. - Add product items using the crm.item.productrow.* methods with
ownerType = SI. - Create a payment using the crm.item.payment.add method and get a link for the client using the salescenter.payment.getPublicUrl method.
- Track the invoice status using the crm.item.get and crm.item.list methods, and change it using the crm.item.update method.
Linking Invoices with Other CRM Objects
Deal. Pass the deal ID in the parentId2 parameter to link the new invoice with the deal.
Estimate. Pass the estimate ID in the parentId7 parameter to link the new invoice with the estimate.
Client. This field in the invoice detail form consists of the associated company and contacts. All activities related to calls, e-mails, and chats with the contact or company will be saved in the invoice detail form. There can be one company in the field, and it is referenced through the invoice field companyId. Multiple contacts can be specified, and interactions with them are managed through the contactIds field; pass an array of contact IDs in this field.
Products. Adding, modifying, and deleting product items in invoices can be done through the group of methods crm.item.productrow.*.
Payments. Adding, modifying, and deleting payment documents in invoices can be done through the group of methods crm.item.payment.*.
Your Company Details. Specify your company ID in the mycompanyId field so that its details are automatically used in documents. You can obtain your company ID using the method crm.item.list: pass entityTypeId = 4 and the filter isMyCompany = Y.
Online Store Orders. An order can be linked to an invoice using the crm.orderentity.* methods by passing ownerTypeId = 31 and the ownerId of the invoice.
User Documentation
Invoice Detail Form
The main workspace in invoices is the General tab of the detail form. It consists of two parts:
-
The left part contains fields with information. If the system fields are insufficient, you can create your own custom fields. These allow you to store information in various data formats: string, number, link, address, and others. To create, modify, retrieve, or delete custom fields for invoices, use the group of methods userfieldconfig.* with
entityId = CRM_SMART_INVOICE. -
The right part contains the invoice timeline. In it, you can create, edit, filter, and delete CRM activities — the group of methods crm.activity.*, and timeline records — the group of methods crm.timeline.*.
The parameters of the invoice detail form can be managed through the group of methods crm.item.details.configuration.*.
User Documentation
Widgets
You can embed an application into the invoice detail form. This allows you to use the application without leaving the invoice detail form.
There are two embedding scenarios:
- Use special embedding locations. For example, by creating your own tab.
- Create a custom field where the interface of your application will be loaded.
Embedding Locations for New Invoices
-
CRM_SMART_INVOICE_DETAIL_TAB— a tab in the detailed view of the CRM object -
CRM_SMART_INVOICE_DETAIL_ACTIVITY— a button above the timeline of the detail form -
CRM_SMART_INVOICE_DETAIL_TOOLBAR— an item in the dropdown menu of the top button in the detail form -
CRM_SMART_INVOICE_DOCUMENTGENERATOR_BUTTON— an item in the dropdown menu of the document generator -
CRM_SMART_INVOICE_LIST_MENU— an item in the context menu in the list of entities -
CRM_SMART_INVOICE_LIST_TOOLBAR— an item in the dropdown menu above the list of entities -
CRM_SMART_INVOICE_ACTIVITY_TIMELINE_MENU— an item in the context menu of an activity in the detail form -
CRM_SMART_INVOICE_ROBOT_DESIGNER_TOOLBAR— an item in the dropdown menu of the top button of the robot designer
Typical use-cases and scenarios
Overview of Methods and Events
Scope:
crm,salescenterWho can execute the method: depending on the method
Main
CRM Object Identifier entityTypeId — 31
|
Method |
Description |
|
Creates a new CRM object |
|
|
Updates an entity |
|
|
Returns an entity by Id |
|
|
Returns a list of entities by filter |
|
|
Deletes an entity |
|
|
Returns the fields of an entity |
|
Event |
Triggered |
|
When an invoice is created manually or via the crm.item.add method |
|
|
When an invoice is modified manually or via the crm.item.update method |
|
|
When an invoice is deleted manually or via the crm.item.delete method |
These events are delivered for items of all smart processes and invoices. To select invoice events, check data.FIELDS.ENTITY_TYPE_ID = 31 in the handler. For details, see the Smart Process Element Events section.
Custom Fields
CRM Object Identifier entityId — CRM_SMART_INVOICE
|
Method |
Description |
|
Creates a custom field |
|
|
Modifies field settings |
|
|
Returns custom field settings by identifier |
|
|
Returns the set of available custom field types for the module |
|
|
Returns a list of custom field settings |
|
|
Deletes a custom field |
|
Event |
Triggered |
|
When a custom field of an invoice is added |
|
|
When the settings of a custom field of an invoice are changed |
|
|
When a custom field of an invoice is deleted |
|
|
When the set of values of a list-type custom field is changed |
Product Items
CRM Object Identifier ownerType — SI
|
Method |
Description |
|
Adds a product item |
|
|
Updates a product item |
|
|
Retrieves information about a product item by id |
|
|
Associates a product item with a CRM object |
|
|
Retrieves a list of product items |
|
|
Retrieves a list of unpaid products |
|
|
Deletes a product item |
|
|
Retrieves a list of product item fields |
Payments
CRM Object Identifier entityTypeId — 31
|
Method |
Description |
|
Creates a payment for a CRM object |
|
|
Modifies the set of payment fields |
|
|
Retrieves brief information about a payment |
|
|
Retrieves a list of payments for a specific CRM object |
|
|
Deletes a payment |
|
|
Changes the payment status to "Paid" |
|
|
Changes the payment status to "Unpaid" |
|
|
Generates a public payment link |
Product Items in Payment
|
Method |
Description |
|
Adds a product item to the payment |
|
|
Retrieves a list of product items in the payment |
|
|
Deletes a product item from the payment |
|
|
Changes the quantity of a product in the payment item |
Delivery in Payment
|
Method |
Description |
|
Adds a delivery item to the payment |
|
|
Retrieves a list of delivery items for a specific payment |
|
|
Deletes a delivery item from the payment |
|
|
Reassociates the delivery item with another delivery document |
Managing Invoice Detail Form Settings
CRM Object Identifier entityTypeId — 31
|
Method |
Description |
|
Retrieves the parameters of the detail form for entities |
|
|
Sets the parameters of the detail form for entities |
|
|
Resets the parameters of the detail form for entities |
|
|
Sets a common detail form for all users |