FINANCE · DOCUMENT NUMBERS
Document Numbering.
Every gap explained.
- Who it helps
- Finance teams whose documents must follow a set numbering format.
- What changes
- Orders, invoices, shipments and credit memos get numbers in your own pattern, with every gap explained.
- Format variables and padded counters
- Counter scope with daily, monthly or yearly reset
- Strict gapless or fast allocation, per series
Number orders, invoices, shipments and credit memos in your own pattern, never twice, with a recorded reason behind every gap.
8.1–8.5
PHP
Compatible
Magento Open Source
3.3 tested
Mage-OS
v 1.0.0 — RELEASED 1 month ago
composer require qoliber/document-number
Product details
Document numbers your accountant will accept.
Magento gives every store one fixed numbering sequence. Finance teams usually need something else: a pattern their market expects, a counter that restarts each year or month, a separate run per country, and an explanation for every number that was never used.
Document Numbering gives orders, invoices, shipments and credit memos a number in your own pattern, never issued twice, with a recorded reason behind every gap. Nothing changes when you install it, so you can move one document type at a time.
Who it is for
- Stores whose invoices must run in unbroken sequences, per year or per month.
- Stores selling into several countries or currencies that must number each one separately.
- Stores with years of existing documents that want the new numbering applied to that history, oldest document first.
- Finance teams and auditors who have to account for every number, including the ones that were never used.
How it works
- Create a series. Compose the format from the date, store, website, billing country, currency, customer group, document type and a padded counter, and preview the next number before anything is issued.
- Set the rules. Choose a counter scope and a daily, monthly or yearly reset, and restrict the series to the stores, websites, customer groups, countries or currencies it belongs to.
- Choose how numbers are allocated. Strict allocation is gapless. Fast allocation gives higher throughput, with every gap still accounted for.
- Read the register. Every number drawn, reserved, converted, expired, refused or changed is recorded in a read-only register.
- Audit it.
qoliber:number:auditexits non-zero on a number nothing explains, so a gap raises an alarm in cron or CI.
Examples
| You set | You get |
|---|---|
FV/{yyyy}/{mm}/{counter:5} with a monthly reset | FV/2026/01/00042, and February starts again from the series' first number |
Counter scope {yyyy}/{mm}/{billingCountry}, format FV/{yyyy}/{mm}/{billingCountry}/{counter:5} | FV/2026/01/PL/00001 and FV/2026/01/DE/00001 in the same month |
Credit memo format KOR/{invoiceNumber}/{counter:4} | KOR/FV/2026/01/00042/0001 |
Also included
- Corrections with a mandatory reason. The old number is retired for good and the change is recorded against the admin user.
- Two-level permissions: staff can correct documents nobody has seen yet, while sent documents need a stronger permission.
- Commands to audit, correct counters, write off abandoned reservations and renumber history.
- A REST API to manage series from your own tooling or deployment pipeline.
Requirements
| PHP | 8.1 to 8.5 |
|---|---|
| Platform | Magento Open Source or Mage-OS on magento/framework ^103.0 with magento/module-sales ^103.0 or ^104.0. Tested on Mage-OS 3.3. |
| Cron | Magento cron. One hourly job writes off checkout reservations whose quote is dead. |
| Storefront | None. The module works in the admin and the backend only, so no Hyvä package is needed. |
Limitations
- Each document type needs its own series, and a document no series matches keeps Magento's own numbering.
- Not every mode is gapless. Fast allocation and reserving order numbers at checkout each use up a number on a failed save or an abandoned checkout. Strict allocation with order numbers allocated on save is gapless.
- The register is never pruned, so it grows for the life of the store. A retention policy is your decision.
- A number is at most 50 characters long.
- Series are configured on their own screens, not under Stores → Configuration.
FAQ
What changes the moment I install it?
Nothing. With no series configured, Magento numbers every document exactly as it did before.
Can two checkouts get the same number?
No. Every number is claimed atomically, and a number already on a document is refused rather than issued a second time.
Can I pass the final order number to my payment gateway?
Yes. Reserve the number at checkout, chosen per series. An abandoned checkout then uses up a number, and the register and audit explain that gap.
Can I renumber existing documents?
Yes. The backfill command applies the numbering to existing documents from the command line, oldest document first.
Does numbering call an outside service?
No. Counters, claims and the register live in your own database.
WHAT IT FIXES
Numbers that match how you file.
Magento gives you a single fixed sequence. Document Numbering composes numbers from the date, store, country, currency and a padded counter, restarts them on schedule and records what happened to every number.
- Format variables and padded counters ● formats
- Counter scope with daily, monthly or yearly reset ● sequences
- Strict gapless or fast allocation, per series ● allocation
- Atomic claims: no number is issued twice ● safe
- Read-only numbering register ● audit trail
- Audit command that fails on an unexplained number ● CI
INSTALL · COMPOSER
Installing changes nothing.
Until you create a series, every document is numbered exactly as Magento numbered it before, so you can move one document type at a time.
# Once per project: add your private qoliber repository # (the exact command is in your account → Composer & keys) composer require qoliber/document-number php bin/magento setup:upgrade ✓ Create your first series when you are ready.
FROM THE COMMUNITY
Customer reviews
Write a review
Write Your Own Review