Invoice Fields in REST 3.0

Choose a tool for developing with an AI agent:

  • use Alaio Vibecode to build an app for Bitrix24 from a task description without knowing any programming language. The agent writes the code and deploys the app to a server, with no manual hosting setup
  • use the MCP server to develop a REST API integration in your own project. The agent refers to the official REST documentation

These fields belong to REST 3.0 methods. The call specifics and response format of the new API version are described in the REST 3.0 overview.

Invoice fields are returned by the crm.smartinvoice.get and crm.smartinvoice.list methods and accepted by the crm.smartinvoice.add and crm.smartinvoice.update methods. Values of multiple fields are added and removed one at a time by the crm.smartinvoice.addfieldvalue and crm.smartinvoice.deletefieldvalue methods. The list of fields with their attributes is returned by the crm.smartinvoice.field.list method.

The crm.smartinvoice.* methods work with new-type invoices, which have entityTypeId = 31. Invoice products are stored separately from the fields and are returned by the crm.smartinvoice.productrow.list method.

Some fields exist in two forms: as an ID and as a related object, for example, assignedById and assignedBy. The ID can be passed when writing data, while the related object can only be requested in select.

Which Fields the Methods Accept and Return

Method

Accepts

Returns

crm.smartinvoice.add

Fields of the Invoice Object table that can be edited, and custom fields. There are no required fields: an invoice is created even with an empty fields object

ID of the created invoice id

crm.smartinvoice.update

Invoice id and the same fields as add. Fields not included in fields keep their current values

Success flag true

crm.smartinvoice.get

Invoice id and select

Without select, only id. With select, only the listed fields; id is not added automatically. A whole related object, for example, assignedBy, returns all of its fields, while a dot-notation path, for example, assignedBy.firstName, returns only the selected ones. For details, see the Related Objects section

crm.smartinvoice.list

select, filter, order, pagination

Without select, only the id of each invoice. Fields and related objects are requested in select the same way as in get

crm.smartinvoice.addfieldvalue, crm.smartinvoice.deletefieldvalue

Invoice id, the multiple field name fieldName, and the value value. Supported fields are contactsId, observersId, and multiple custom fields. For other fields, the method returns the error "The field is not supported."

Success flag true

The add and update methods do not accept fields marked "read-only" and return the BITRIX_REST_V3_EXCEPTION_VALIDATION_DTOVALIDATIONEXCEPTION error with the message 'Field "taxValue" is read-only.' Related objects, for example, company and stage, are also read-only: to write data, pass the ID — companyId, stageId.

The method validates fields with values from reference lists when writing data. If the value is not in the reference list, the method returns the error 'Field value is not one of the possible values'. For the stage, source, and currency, the error message lists the allowed values.

Boolean fields accept and return true or false. The values Y, N, 1, and 0 are not accepted: the method returns the error 'This request requires data type "bool" in field "opened"'.

Fields of the date type — beginTime and closeTime — accept and return a date in the YYYY-MM-DD format, for example, 2026-11-03. Such a field does not accept a date with time or a date in the 03.11.2026 format. Fields of the datetime type are returned in ISO 8601 format, for example, 2026-11-03T14:52:21+03:00. In a filter by a datetime field, also pass a date with time.

You can filter and sort only by the fields whose description says so. For other fields, the list method returns an error stating that the field 'requires attribute "Filterable"' or '"Sortable"'. Dot notation lets you filter by fields of linked CRM items and of the lastCommunication object, for example, ["company.title", "=", "Müller GmbH"] or ["myCompany.title", "=", "My company"]. Filtering by fields of employees, stage, and source, for example, assignedBy.id or stage.semanticId, is not supported: the method returns the BITRIX_REST_V3_EXCEPTION_INVALIDFILTEREXCEPTION error. The filter format is described on the crm.<type>.list page and in the REST API 3.0 Overview article.

The closed, stageSemanticId, and stageSemantic fields are present in the crm.smartinvoice.field.list response, but the get and list methods do not accept them. For such a field in select, filter, or order, the method returns the BITRIX_REST_V3_EXCEPTION_UNKNOWNDTOPROPERTYEXCEPTION error. The stage group can be retrieved from the semanticId field of the stage object: "select": ["stage.semanticId"].

Invoice Object

Name
type

Description

id
integer

Invoice ID. Assigned on creation.

Read-only. Can be filtered and sorted

title
string

Invoice title, up to 255 characters. If the title is not passed on creation, Bitrix24 sets the word "Invoice" and the ID, for example, Invoice #141. crm.smartinvoice.update does not write an empty string: the title stays unchanged.

Can be edited, filtered, and sorted

accountNumber
string

Invoice number, for example, INV-001. If the number is not passed on creation, Bitrix24 assigns it according to the invoice numbering settings.

Can be edited, filtered, and sorted

xmlId
string | null

External code of the invoice, up to 255 characters. Use it to link the invoice to a record in an external system.

Can be edited, filtered, and sorted

stageId
string

Stage ID, for example, DT31_5:N. If the stage is not passed on creation, the invoice is placed at the first stage. REST 3.0 has no separate method for invoice stages. Stages are returned by the crm.status.list method with the filter {"ENTITY_ID": "SMART_INVOICE_STAGE_5"}, where 5 is the pipeline number from stageId. The allowed stages are also listed in the error message if an invalid value is passed.

Can be edited, filtered, and sorted

stage
object

Invoice stage. An object of type stage.

Read-only. Requested in select

movedTime
datetime

Date and time of the last stage change.

Read-only. Can be filtered and sorted

movedById
integer

ID of the user who last changed the stage.

Read-only. Can be filtered and sorted

movedBy
object

User who last changed the stage. An object of type employee.

Read-only. Requested in select

closed
boolean

Whether the invoice is closed: true — yes, false — no.

Read-only. The field is present in the field.list response, but the get and list methods do not accept it and return the BITRIX_REST_V3_EXCEPTION_UNKNOWNDTOPROPERTYEXCEPTION error

stageSemanticId
string

Stage group. Possible values:

  • P — in progress
  • S — successful
  • F — unsuccessful

Read-only. The field is present in the field.list response, but the get and list methods do not accept it and return the BITRIX_REST_V3_EXCEPTION_UNKNOWNDTOPROPERTYEXCEPTION error. The stage group is returned by the stage.semanticId field

stageSemantic
object

Stage group with its name: id and name. The reference list of groups is returned by the crm.dictionary.stagesemantic.list method.

Read-only. The field is present in the field.list response, but the get and list methods do not accept it and return the BITRIX_REST_V3_EXCEPTION_UNKNOWNDTOPROPERTYEXCEPTION error

beginTime
date

Invoice date. If not passed on creation, Bitrix24 sets the invoice creation date.

Can be edited, filtered, and sorted

closeTime
date

Payment due date. If not passed on creation, Bitrix24 sets the date seven days after the invoice is created.

Can be edited, filtered, and sorted

opportunity
double

Invoice amount, not less than 0. For a negative value, the method returns the error 'Field value must be 0 or greater'. The way the amount is calculated is set by the isManualOpportunity field.

Can be edited, filtered, and sorted

isManualOpportunity
boolean

Amount calculation mode: true — the amount is set manually, false — the amount is calculated from the product rows. Defaults to false.

Can be edited, filtered, and sorted

taxValue
double

Tax amount. Calculated from the product rows.

Read-only. Can be filtered and sorted

currencyId
string

Currency ID, for example, EUR. If not passed on creation, Bitrix24 sets the base currency. Currencies are returned by the crm.currency.list method.

Can be edited, filtered, and sorted

currency
object

Currency. An object of type currency.

Read-only. Requested in select

companyId
integer | null

Client company ID. Companies are returned by the crm.company.list method.

Can be edited, filtered, and sorted

company
object | null

Client company. An object of type CRM item.

Read-only. Requested in select

contactsId
integer[]

IDs of the invoice contacts. Contacts are returned by the crm.contact.list method. The passed array replaces the current list of contacts.

Can be edited and filtered, cannot be sorted

contacts
object[]

Invoice contacts. An array of objects of type CRM item. If there are no contacts, an empty array.

Read-only. Requested in select

contactId
integer | null

ID of the primary contact, which is the first one in the contactsId list. To set the primary contact, use the crm.smartinvoice.setprimarycontact method.

Read-only. Can be filtered, cannot be sorted

contact
object | null

Primary contact. An object of type CRM item.

Read-only. Requested in select

myCompanyId
integer | null

ID of your company on whose behalf the invoice is issued. If not passed on creation, Bitrix24 sets your default company. The list of your companies is returned by the crm.mycompany.list method. The method does not accept a client company ID and returns the error 'Field value is not one of the possible values'. The requisites of your company in the invoice are set by the crm.smartinvoice.mycompanyrequisite.set method.

Can be edited, filtered, and sorted

myCompany
object | null

Your company. An object of type CRM item. Its fields are described in the My Company Fields in REST 3.0 article.

Read-only. Requested in select

relatedDealId
integer | null

ID of the deal the invoice belongs to. If there is no such deal, the method returns the error 'Field value is not one of the possible values'.

Can be edited and filtered, cannot be sorted

relatedDeal
object | null

Deal the invoice belongs to. An object of type CRM item.

Read-only. Requested in select

relatedQuoteId
integer | null

ID of the estimate the invoice belongs to. If there is no such estimate, the method returns the error 'Field value is not one of the possible values'.

Can be edited and filtered, cannot be sorted

relatedQuote
object | null

Estimate the invoice belongs to. An object of type CRM item.

Read-only. Requested in select

locationId
integer | null

Location ID. If the location is not set, 0. If the location does not exist in Bitrix24, the method returns the error 'Field value is not one of the possible values'.

Can be edited, filtered, and sorted

sourceId
string | null

Source ID, for example, WEB. Sources are returned by the crm.dictionary.source.list method.

Can be edited, filtered, and sorted

source
object | null

Source. An object of type reference list value.

Read-only. Requested in select

sourceDescription
string | null

Additional information about the source.

Can be edited and filtered, cannot be sorted

assignedById
integer

ID of the person responsible for the invoice. If not passed on creation, the user who called the method becomes the responsible person. User IDs are returned by the user.get method. If the user does not exist, the method returns the error 'Field value is not one of the possible values'.

Can be edited, filtered, and sorted

assignedBy
object

Responsible person. An object of type employee.

Read-only. Requested in select

observersId
integer[]

Observer IDs. User IDs are returned by the user.get method. The passed array replaces the current list of observers.

Can be edited and filtered, cannot be sorted. In a filter, ["observersId", "=", 1] finds invoices that have user 1 among their observers

observers
object[]

Observers. An array of objects of type employee. If there are no observers, an empty array.

Read-only. Requested in select

opened
boolean

Whether the invoice is available to all users: true — yes, false — no.

Can be edited, filtered, and sorted

comments
string | null

Comment on the invoice.

Can be edited. Cannot be filtered or sorted

createdTime
datetime

Date and time the invoice was created.

Read-only. Can be filtered and sorted

createdById
integer

ID of the user who created the invoice.

Read-only. Can be filtered and sorted

createdBy
object

User who created the invoice. An object of type employee.

Read-only. Requested in select

updatedTime
datetime

Date and time the invoice was last updated.

Read-only. Can be filtered and sorted

updatedById
integer

ID of the user who last updated the invoice.

Read-only. Can be filtered and sorted

updatedBy
object

User who last updated the invoice. An object of type employee.

Read-only. Requested in select

lastActivityTime
datetime

Date and time of the last activity in the invoice timeline.

Read-only. Can be filtered and sorted

lastActivityById
integer

ID of the author of the last activity in the timeline.

Read-only. Can be filtered and sorted

lastActivityBy
object

Author of the last activity in the timeline. An object of type employee.

Read-only. Requested in select

webformId
integer | null

ID of the CRM form through which the invoice was created. If the invoice was not created by a form, null. The list of forms is returned by the crm.form.list method.

Read-only. Can be filtered and sorted

webform
object | null

CRM form through which the invoice was created. An object of type CRM form.

Read-only. Requested in select

lastCommunication
object

Dates of the last communications on the invoice. An object of type last communication.

Read-only. Requested in select. Can be filtered by object fields using dot notation, for example, ["lastCommunication.callTime", ">=", "2026-11-01T00:00:00+03:00"]

entityTypeId
integer

Object type ID. For an invoice, 31.

Read-only

canRead
boolean

Whether the current user can view the invoice: true — yes, false — no.

Read-only

url
string

Relative link to the invoice card, for example, /crm/type/31/details/139/?categoryId=5.

Read-only

Related Objects

A related object is requested in select by the field name without the Id suffix: assignedBy, stage, company. The whole object name returns all of its fields, and a dot-notation path returns only the selected ones, for example, ["stage.name", "assignedBy.firstName"]. The path supports one level of nesting.

A linked CRM item — contact, contacts, company, myCompany, relatedDeal, relatedQuote — returns only id when requested by its whole name. Request the other item fields using dot notation. Dot notation gives access to the fields of the CRM item object and to any fields of the linked item's type, for example, ["company.title", "company.phone", "myCompany.title"].

If a link is not set, the object is returned as null, and an array of objects, for example, observers or contacts, is returned as an empty array.

Employee Object

Fields createdBy, updatedBy, lastActivityBy, assignedBy, movedBy, observers.

Name
type

Description

id
integer

User ID

firstName
string

First name

lastName
string

Last name

personalGender
string | null

Gender: M — male, F — female. If the gender is not specified, null

url
string

Relative link to the user profile, for example, /company/personal/user/1/

personalPhoto
string | null

Link to the user photo. If there is no photo, null

CRM Item Object

Fields contact, contacts, company, myCompany, relatedDeal, relatedQuote.

Name
type

Description

id
integer

Item ID

entityTypeId
integer

Object type ID, for example, 3 — contact, 4 — company, 2 — deal

canRead
boolean

Whether the current user can view the item

title
string

Item title. For a contact, the last name, first name, and middle name

url
string

Relative link to the item card, for example, /crm/company/details/3159/

Stage Object

Field stage.

Name
type

Description

id
string

Stage ID, for example, DT31_5:P

name
string

Stage name, for example, Paid

sort
integer

Stage order in the pipeline

color
string

Stage color in the #RRGGBB format

semanticId
string

Stage group: P — in progress, S — successful, F — unsuccessful

Reference List Value Object

Field source.

Name
type

Description

id
string

Value ID, for example, WEB

name
string

Value name, for example, Website

sort
integer

Sort order

CRM Form Object

Field webform.

Name
type

Description

id
integer

CRM form ID

name
string

CRM form name

Last Communication Object

Field lastCommunication. If there has been no communication of a given kind, the corresponding field is null.

Name
type

Description

communicationTime
datetime | null

Date and time of the last communication of any kind

callTime
datetime | null

Date and time of the last call

emailTime
datetime | null

Date and time of the last email

imolTime
datetime | null

Date and time of the last message in an open channel

webformTime
datetime | null

Date and time the CRM form was last submitted

Currency Object

Field currency.

Name
type

Description

id
string

Currency code, for example, EUR

fullName
string

Currency name

formatString
string

Amount display template. The # character is replaced with the amount. The currency sign is returned as an HTML entity, for example, &euro;#

decPoint
string

Decimal separator

thousandsSep
string

Thousands separator. May be returned as an HTML entity, for example, &nbsp;

decimals
integer

Number of decimal places

hideZero
boolean

Whether to hide insignificant trailing zeros in the fractional part

amount
double

Exchange rate relative to the base currency

amountCount
integer

Number of currency units the exchange rate applies to

base
boolean

Base currency: true — yes, false — no

sort
integer

Sort order

numericCode
string

Numeric currency code, for example, 978

languageId
string

Language for which the name and format are set

createdTime
datetime | null

Date and time the currency was created

updatedTime
datetime | null

Date and time the currency was updated

createdById
integer | null

ID of the user who created the currency

updatedById
integer | null

ID of the user who updated the currency

Custom Fields

Custom invoice fields are named UF_CRM_SMART_INVOICE_<code> or UF_CRM_<code>, for example, UF_CRM_619F45A0AF6DB. They are passed and requested by name in the same way as standard fields. The list of custom invoice fields is returned by the crm.smartinvoice.field.custom.list method.

The value of a "Money" field is passed as an object {"sum": 150.5, "currencyId": "EUR"}. A string such as 150.5|EUR is not accepted: the method returns the error 'This request requires data type "MoneyDto" in field "UF_CRM_…"'.

Each custom field has a paired UF_CRM_…_data field, which is read-only and requested in select. It contains the value in several representations:

  • value — the value in the same format as in the field itself
  • rawValue — the value in the storage format, for example, 150.5|EUR for a "Money" field
  • formattedValue — the value for display to the user: 150.50 € for money, the employee name for a "Link to employee" field
  • extra — additional data: for money, amount, currencyId, and currencyFullName; for an employee, the fields of the employee object. For a string, number, and date, null

For a multiple custom field, UF_CRM_…_data is an array of such objects.

Continue Learning

Previous
Estimate Fields
Next
SPA Fields