HomeGuidesRecipesAPI ExplorerForumSupport
Partner Portal
Partner Portal

Document number customization

Learn how to customize the numbering sequence of documents issued using the Monite API.

Suggest Edits

Overview

Monite automatically generates document numbers to help entities keep track of issued payables and receivables. By default, all document IDs have only a prefix and suffix, with the document type representing the prefix and the document number representing the suffix—INV-00001, PO-00031. This approach ensures that all document IDs are unique and sequential across all document types.

Monite allows entities to customize the format of their document numbers. This includes the ability to customize the prefix for all document types, the option to include the current year on documents, the ability to customize the minimum number of digits on document IDs, and so on.

How it works

Whenever an entity issues a new receivable or purchase order, Monite automatically assigns the next available number in the sequence for that document type. Monite's default sequence combines a fixed prefix that depends on the document type—such as INV or PO—with a sequentially increasing number—such as 00001. For example, when an entity issues its first invoice, Monite assigns the document_id of INV-00001 to this invoice. Monite will then assign sequential document IDs to subsequent invoices issued by that entity —INV-00002, INV-00003, and so on.

Monite allows entities to change the default sequence that the system adopts when assigning document IDs. Entities can change the prefixes for corresponding document types and adjust the digit padding for document IDs by using the document_ids field on the PATCH /entities/{entity_id}/settings endpoint. They can also further customize document prefixes and change the next number in the sequence for each document type.

Monite's document number ordering

A customized document number sequence.


📘

There is no way to customize the order of prefixes in Monite documents. For example, all invoices issued by an entity that opted to include the current year and has a custom prefix will be of the following format: IN/EX-ORG/2024/00003.

The following snippet shows a PATCH request to the /entities/{entity_id}/settings endpoint updating the document_ids object:

curl -X PATCH 'https://api.sandbox.monite.com/v1/entities/5b031d0c...44df31ebf0db/settings' \
     -H 'X-Monite-Version: 2024-01-31' \
     -H 'Authorization: Bearer YOUR_PARTNER_TOKEN' \
     -H 'Content-Type: application/json' \
     -d '{
      "document_ids": {
        "include_date": true,
        "prefix": null,
        "separator": "-",
        "min_digits": 3,
        "document_type_prefix": {
          "quote": "Q",
          "invoice": "INV",
          "credit_note": "CN",
          "purchase_order": "PO"
        },
        "next_number": {
          "quote": 5,
          "invoice": 20,
          "credit_note": 7,
          "purchase_order": 10
         }
       }
     }'
  • The document_type_prefix and next_number fields allow you to customize for individual document types. Monite will apply updates to any other fields within the document_ids object across all document types.
  • The separator field refers to the character that separates document prefixes from the document number or document prefixes from other document prefixes. Its value can either be an empty string or one of the following: /, -, |, ..

Manage document prefixes

Document prefixes refer to the characters before the document number. This includes the current year, the entity's custom prefix, and the document type prefix. All prefixes are separated by the defined separator character.

📘

Updating document prefixes does not reset the document number for any document. For example, suppose the document_id of the entity's last issued invoice was INV-00007, and the entity updated the document prefix for invoices to INV/EX-ORG. In that case, the invoice number for the next invoice issued by the entity will be INV/EX-ORG/00008.

Document type prefix

Document type prefixes are document identifiers used to denote the type of document. They are represented by the document_type_prefix field on the document_ids object.

The default prefixes are:

  • INV – for sales invoices
  • Q – for quotes
  • CN – for credit notes
  • PO – for purchase orders

Monite allows entities to modify the value of this field. Its value must be a non-empty string; null and empty strings are not accepted.

To update a document type prefix: 

curl -X PATCH 'https://api.sandbox.monite.com/v1/entities/5b031d0c...44df31ebf0db/settings' \
     -H 'X-Monite-Version: 2024-01-31' \
     -H 'Authorization: Bearer YOUR_PARTNER_TOKEN' \
     -H 'Content-Type: application/json' \
     -d '{
      "document_ids": {
        "document_type_prefix": {
          "quote": "QU",
          "invoice": "IN"
        }
       }
     }'

Custom prefix

A custom prefix refers to any prefix defined by the entity. This is represented by the prefix field on the document_ids object. These prefixes are optional, but when provided, they apply to all document types provided by the Monite API.

Whenever a custom prefix is used, Monite will combine this value with the value of the document_type_prefix for all documents. For example, an invoice issued by Example Organization could have a document_id of IN/EX-ORG/00003.

Including the current year

Entities can also opt to include the current year in document prefixes by setting the include_date field on the document_ids object to true.

Manage document number

The document number refers to the unique identifier for a particular document type. Monite allows you to set the minimum number of digits and choose the next number for all documents.

Update the minimum number of digits

You can update the minimum number of digits for all document types. This is useful when an entity needs to adjust the number of leading zeros on issued documents.

To update the minimum number of digits, use the min_digits field on the document_ids object. If the value provided is more than the number of digits in the document ID number, the document number is padded with zeros. For example, if an entity set a min_digits value of 3, the third invoice issued by this entity will have a document_id of IN/EX-ORG/003, while the twelfth invoice has a document_id of IN/EX-ORG/012.

📘

The value of the min_digits field applies to all document types. This value does not affect the maximum number of digits in the document number. Therefore, entities with a min_digits value of 3 can have document numbers greater than or equal to 1000.

Set the next document number

Monite allows entities to set the next document number for all document types. This is useful when an entity migrates from another payables or receivables provider and wants to continue with its existing numbering system.

To set the next document number, use the next_number field on the document_ids object as shown:

curl -X PATCH 'https://api.sandbox.monite.com/v1/entities/5b031d0c...44df31ebf0db/settings' \
     -H 'X-Monite-Version: 2024-01-31' \
     -H 'Authorization: Bearer YOUR_PARTNER_TOKEN' \
     -H 'Content-Type: application/json' \
     -d '{
      "document_ids": {
        "next_number": {
          "quote": 5,
          "invoice": 20
         }
       }
     }'

The document number provided in the request object must exceed the current existing document number for the document type. Attempting to use a lower number will throw an error.

Updated about 2 months ago