invoice.md

Invoices: Overview of Methods and Events

{% note tip "" %}

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.

{% endnote %}

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.

{% note warning "" %}

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.

{% endnote %}

Quick navigation: all methods and events

User documentation: New invoices in CRM

Getting Started

1. Retrieve the list of available invoice fields using the crm.item.fields method with entityTypeId = 31.
2. Create an invoice using the crm.item.add method. Link it to a deal through parentId2 and specify the client in the companyId and contactIds fields.
3. Add product items using the crm.item.productrow.* methods with ownerType = SI.
4. Create a payment using the crm.item.payment.add method and get a link for the client using the salescenter.payment.getPublicUrl method.
5. 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.

{% note tip "User Documentation" %}

• How to accept payments from clients and work with receipts in Bitrix24
• How to add products to deals, leads, and estimates
• How to use your company details

{% endnote %}

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.*.

{% note tip "User Documentation" %}

• CRM Detail Form: Features and Settings
• System Fields in CRM
• Custom Fields in CRM
• Timeline in CRM item form

{% endnote %}

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

{% note tip "Typical use-cases and scenarios" %}

• Widget Embedding Mechanism
• Embed a Widget in the CRM Detail Form

{% endnote %}

Overview of Methods and Events {#all-methods}

Scope: crm, salescenter

Who can execute the method: depending on the method

Main

CRM Object Identifier entityTypeId — 31

{% list tabs %}

• Methods

  #| || Method | Description || || crm.item.add | Creates a new CRM object || || crm.item.update | Updates an entity || || crm.item.get | Returns an entity by Id || || crm.item.list | Returns a list of entities by filter || || crm.item.delete | Deletes an entity || || crm.item.fields | Returns the fields of an entity || |#

• Events

  #| || Event | Triggered || || onCrmDynamicItemAdd | When an invoice is created manually or via the crm.item.add method || || onCrmDynamicItemUpdate | When an invoice is modified manually or via the crm.item.update method || || onCrmDynamicItemDelete | 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.

{% endlist %}

Custom Fields

CRM Object Identifier entityId — CRM_SMART_INVOICE

{% list tabs %}

• Methods

  #| || Method | Description || || userfieldconfig.add | Creates a custom field || || userfieldconfig.update | Modifies field settings || || userfieldconfig.get | Returns custom field settings by identifier || || userfieldconfig.getTypes | Returns the set of available custom field types for the module || || userfieldconfig.list | Returns a list of custom field settings || || userfieldconfig.delete | Deletes a custom field || |#

• Events

  #| || Event | Triggered || || onCrmTypeUserFieldAdd | When a custom field of an invoice is added || || onCrmTypeUserFieldUpdate | When the settings of a custom field of an invoice are changed || || onCrmTypeUserFieldDelete | When a custom field of an invoice is deleted || || onCrmTypeUserFieldSetEnumValues | When the set of values of a list-type custom field is changed || |#

{% endlist %}

Product Items

CRM Object Identifier ownerType — SI

#| || Method | Description || || crm.item.productrow.add | Adds a product item || || crm.item.productrow.update | Updates a product item || || crm.item.productrow.get | Retrieves information about a product item by id || || crm.item.productrow.set | Associates a product item with a CRM object || || crm.item.productrow.list | Retrieves a list of product items || || crm.item.productrow.getAvailableForPayment | Retrieves a list of unpaid products || || crm.item.productrow.delete | Deletes a product item || || crm.item.productrow.fields | Retrieves a list of product item fields || |#

Payments

CRM Object Identifier entityTypeId — 31

#| || Method | Description || || crm.item.payment.add | Creates a payment for a CRM object || || crm.item.payment.update | Modifies the set of payment fields || || crm.item.payment.get | Retrieves brief information about a payment || || crm.item.payment.list | Retrieves a list of payments for a specific CRM object || || crm.item.payment.delete | Deletes a payment || || crm.item.payment.pay | Changes the payment status to "Paid" || || crm.item.payment.unpay | Changes the payment status to "Unpaid" || || salescenter.payment.getPublicUrl | Generates a public payment link || |#

Product Items in Payment

#| || Method | Description || || crm.item.payment.product.add | Adds a product item to the payment || || crm.item.payment.product.list | Retrieves a list of product items in the payment || || crm.item.payment.product.delete | Deletes a product item from the payment || || crm.item.payment.product.setQuantity | Changes the quantity of a product in the payment item || |#

Delivery in Payment

#| || Method | Description || || crm.item.payment.delivery.add | Adds a delivery item to the payment || || crm.item.payment.delivery.list | Retrieves a list of delivery items for a specific payment || || crm.item.payment.delivery.delete | Deletes a delivery item from the payment || || crm.item.payment.delivery.setDelivery | Reassociates the delivery item with another delivery document || |#

Managing Invoice Detail Form Settings

CRM Object Identifier entityTypeId — 31

#| || Method | Description || || crm.item.details.configuration.get | Retrieves the parameters of the detail form for entities || || crm.item.details.configuration.set | Sets the parameters of the detail form for entities || || crm.item.details.configuration.reset | Resets the parameters of the detail form for entities || || crm.item.details.configuration.forceCommonScopeForAll | Sets a common detail form for all users || |#

Continue Learning

• {#T}
• {#T}
• {#T}