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 that tracks the next sequential number
• A template — a pattern that combines date tokens, a separator, and the counter (e.g., YYYY/MM/id produces 2026/03/0042)
• A pad length — how many digits the counter is zero-padded to (default: 4)

When you request the next number, the engine formats the current date using the template, appends the zero-padded counter, and checks for uniqueness against existing invoices.

---

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/v2/invoices/next-number

Response (200 OK)

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

Example: Get next number with custom template

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

Response (200 OK)

{
  "invoiceNumber": "2026-0042",
  "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/v2/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/v2/settings/invoice-number-template

Response (200 OK)

{
  "template": "YYYY/MM/id",
  "padLength": 4,
  "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/v2/settings/invoice-number-template

Response (200 OK)

{
  "template": "YYYY-id",
  "padLength": 4,
  "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/v2/settings/invoice-number-template

Response (200 OK)

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

With padLength: 6, the next number would be 2026/03/000042 instead of 2026/03/0042.

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: