Numbering Sequences API

Numbering sequences produce sequential, formatted document numbers (for example INV-2026-00001) so you don't have to track counters yourself. A sequence combines a static prefix, a date_pattern, and a zero-padded incrementing number, and can automatically reset the counter each year or month. Reference a sequence when generating invoice numbers — including from recurring invoices.

A generated number is composed as prefix + date_pattern + zero-padded next_number. The date_pattern supports these tokens, which are substituted using the current date at generation time:

• {YYYY} — four-digit year (e.g. 2026)
• {YY} — two-digit year (e.g. 26)
• {MM} — two-digit month (e.g. 08)

Create Numbering Sequence

POST /api/v1/numbering-sequences

Request:

{
  "name": "Default invoice sequence",
  "document_type": "invoice",
  "prefix": "INV-",
  "date_pattern": "{YYYY}-",
  "padding": 5,
  "next_number": 1001,
  "reset": "yearly"
}

Field	Required	Description
name	Yes	Display name for the sequence
document_type	No	invoice or credit_note (default invoice)
prefix	No	Static prefix prepended to every number (default INV-)
date_pattern	No	Date token pattern (default {YYYY}-)
padding	No	Zero-pad the number to this width, 1–10 (default 5)
next_number	No	The next value to be issued, ≥ 1 (default 1)
reset	No	Counter reset policy: never, yearly, or monthly (default yearly)

Response 200 OK:

{
  "data": {
    "id": "seq_01ABC",
    "name": "Default invoice sequence",
    "document_type": "invoice",
    "prefix": "INV-",
    "date_pattern": "{YYYY}-",
    "padding": 5,
    "next_number": 1001,
    "reset": "yearly",
    "created_at": "2026-07-20T10:00:00Z",
    "updated_at": "2026-07-20T10:00:00Z"
  }
}

Try it

List Numbering Sequences

GET /api/v1/numbering-sequences?limit=50

Response:

{
  "data": [
    {
      "id": "seq_01ABC",
      "name": "Default invoice sequence",
      "document_type": "invoice",
      "prefix": "INV-",
      "date_pattern": "{YYYY}-",
      "padding": 5,
      "next_number": 1001,
      "reset": "yearly",
      "created_at": "2026-07-20T10:00:00Z",
      "updated_at": "2026-07-20T10:00:00Z"
    }
  ],
  "pagination": {
    "has_more": false,
    "next_cursor": null
  }
}

Try it

Get Numbering Sequence

GET /api/v1/numbering-sequences/{sequence_id}

Response:

{
  "data": {
    "id": "seq_01ABC",
    "name": "Default invoice sequence",
    "document_type": "invoice",
    "prefix": "INV-",
    "date_pattern": "{YYYY}-",
    "padding": 5,
    "next_number": 1001,
    "reset": "yearly",
    "created_at": "2026-07-20T10:00:00Z",
    "updated_at": "2026-07-20T10:00:00Z"
  }
}

Try it

Update Numbering Sequence

PATCH /api/v1/numbering-sequences/{sequence_id}

Only include the fields you want to change:

{
  "prefix": "INV-2026-",
  "padding": 6,
  "next_number": 2000
}

Field	Required	Description
name	No	Display name
prefix	No	Static prefix
date_pattern	No	Date token pattern
padding	No	Zero-pad width, 1–10
next_number	No	The next value to be issued, ≥ 1
reset	No	never, yearly, or monthly

Note

document_type is fixed at creation time and cannot be changed via update.

Response 200 OK: the updated numbering sequence object (same shape as Get Numbering Sequence).

Try it

Delete Numbering Sequence

DELETE /api/v1/numbering-sequences/{sequence_id}

Response:

{
  "data": {
    "deleted": true
  }
}

Try it

Preview Next Number

POST /api/v1/numbering-sequences/{sequence_id}/preview

Returns what the next generated number would look like, applying the date pattern, padding, and any pending reset. This is a read-only preview — the counter is not advanced.

Response 200 OK:

{
  "data": {
    "next": "INV-2026-01001"
  }
}

Try it

Consume Next Number

POST /api/v1/numbering-sequences/{sequence_id}/next

Advances the sequence, incrementing next_number by one. Returns the updated sequence reflecting the new counter value.

Response 200 OK:

{
  "data": {
    "id": "seq_01ABC",
    "name": "Default invoice sequence",
    "document_type": "invoice",
    "prefix": "INV-",
    "date_pattern": "{YYYY}-",
    "padding": 5,
    "next_number": 1002,
    "reset": "yearly",
    "created_at": "2026-07-20T10:00:00Z",
    "updated_at": "2026-07-20T14:00:00Z"
  }
}

Try it