Invoice Numbers

This section covers how to generate, verify, and configure invoice numbers via the API. The invoice number engine supports configurable templates with date placeholders, automatic sequential numbering, and uniqueness checks.

---

How Invoice Numbers Work

Each user account maintains:

• A counter — an auto-incrementing integer holding the last invoice number used. The next invoice gets counter + 1.
• A template — a pattern that combines date tokens, a separator, and the counter (e.g., YYYY/MM/id produces 2026/03/00043 when counter is 42 and padLength is 5).
• A pad length — how many digits the next number is zero-padded to (default for new accounts: 5).

When you request the next number, the engine reads the current counter, increments it by one, formats the date and applies the pad, and checks for uniqueness against existing invoices. GET /invoices/next-number is a preview — it does not allocate the number; allocation happens when the invoice is actually created.

---

Invoice Number API Endpoints

All invoice number endpoints require apiKeyAuth.

Endpoint	Method	Description
GET /invoices/next-number	GET	Generate the next available invoice number
GET /invoices/verify-number	GET	Check if a specific invoice number is available
GET /settings/invoice-number-template	GET	Get the current template, pad length, and counter
PUT /settings/invoice-number-template	PUT	Update the invoice number template and/or pad length

---

Get Next Invoice Number

Returns the next available invoice number. The number is verified for uniqueness — if a collision is detected, the counter is automatically incremented until a unique number is found.

Example: Get next number with default template

curl -H "X-API-KEY: your-api-token" \
     https://api.faktoora.com/api/v1/invoices/next-number

Response (200 OK)

{
  "invoiceNumber": "2026/03/00043",
  "counter": 42
}

counter is the last used number (42); the previewed invoiceNumber embeds counter + 1 (43), zero-padded to the configured padLength (5 for new accounts).

Example: Get next number with custom template

curl -H "X-API-KEY: your-api-token" \
     "https://api.faktoora.com/api/v1/invoices/next-number?template=YYYY-id"

Response (200 OK)

{
  "invoiceNumber": "2026-00043",
  "template": "YYYY-id",
  "counter": 42
}

Template Format

The template query parameter must end with a separator followed by id:

Template	Example Output	Description
YYYY/MM/id	2026/03/0042	Year/month/number (default)
YYYY-id	2026-0042	Year-number
MM/YYYY/id	03/2026/0042	Month/year/number
YYYY/id	2026/0042	Year/number

The date portion supports any dayjs format tokens: YYYY, YY, MM, DD, etc. The separator before id can be / or -.

---

Verify Invoice Number

Check whether a specific invoice number is already in use. Returns available: true if the number can be used for a new invoice.

Example: Verify a number

curl -H "X-API-KEY: your-api-token" \
     "https://api.faktoora.com/api/v1/invoices/verify-number?value=2026/03/0042"

Response (200 OK)

{
  "available": true,
  "invoiceNumber": "2026/03/0042"
}

Example: Number already in use

{
  "available": false,
  "invoiceNumber": "2026/03/0001"
}

Note: Draft and temporary invoices are excluded from the uniqueness check. Only published invoices count.

---

Get Template Settings

Retrieve the current invoice number template configuration, including the pad length and the current counter value.

Example: Get current settings

curl -H "X-API-KEY: your-api-token" \
     https://api.faktoora.com/api/v1/settings/invoice-number-template

Response (200 OK)

{
  "template": "YYYY/MM/id",
  "padLength": 5,
  "currentCounter": 42
}

---

Update Template Settings

Update the invoice number template and/or the pad length. Both fields are optional — you can update one without affecting the other.

Example: Change template to year-only

curl -X PUT \
  -H "X-API-KEY: your-api-token" \
  -H "Content-Type: application/json" \
  -d '{ "template": "YYYY-id" }' \
  https://api.faktoora.com/api/v1/settings/invoice-number-template

Response (200 OK)

{
  "template": "YYYY-id",
  "padLength": 5,
  "currentCounter": 42
}

Example: Change pad length

curl -X PUT \
  -H "X-API-KEY: your-api-token" \
  -H "Content-Type: application/json" \
  -d '{ "padLength": 6 }' \
  https://api.faktoora.com/api/v1/settings/invoice-number-template

Response (200 OK)

{
  "template": "YYYY/MM/id",
  "padLength": 6,
  "currentCounter": 42
}

With padLength: 6 and currentCounter: 42, the next number would be 2026/03/000043 (counter + 1, padded to 6) instead of 2026/03/00043 (the default-5 padding).

Validation Rules

Field	Type	Constraints
template	string	Must end with -id or /id
padLength	integer	Minimum: 1, maximum: 10

---

Typical Integration Flow

A common pattern when creating invoices via the API:

For high-concurrency scenarios where multiple systems create invoices simultaneously, the engine uses distributed locking to prevent duplicate numbers. However, if you request a number and don't use it immediately, another process could claim it. In that case, verify before submitting: