Document numbering

Most numbered documents in the suite — a quote, a sales order, an invoice, a case, a journal entry — take their number from the same engine, and where they do, the numbering scheme is configuration, not code: an administrator writes a format template, says when the counter should restart, and the engine renders the number when the document is created.

That engine lives in the shared platform library, so CRM, CPQ and Accounts all parse the same template syntax, enforce the same rules, and mint numbers the same way. Each product then ships its own screen over it, covering its own document types and storing its own counters. What follows is the model; the divergences section is where the three products part company, and they part company in ways that matter.

Writing a format

A format is literal text plus tokens in braces. Anything outside the braces is copied through exactly as typed.

Token	Renders	Example
{SEQ}	The running counter, unpadded	42
{SEQ:5}	The counter, zero-padded to five digits	00042
{00000}	The same thing written as a run of zeros	00042
{YYYY}	Four-digit year	2026
{YY}	Two-digit year	26
{MM}	Two-digit month	07
{DD}	Two-digit day	24
{Q}	Calendar quarter, 1–4	3

So INV-{YYYY}-{SEQ:5} produces INV-2026-00042, and CAS-{SEQ:6} produces CAS-000042.

Three rules the editor enforces:

• Exactly one sequence token. A format with two counters, or none at all, is rejected.
• Padding is 1 to 18 digits. {SEQ} counts as a padding of one.
• Unknown tokens are errors. A misspelled {YEAR} is not silently printed as literal text; the save is refused and the token is named in the message.

Alongside the format each document type carries three numbers:

• Start value — the first number of each period.
• Increment — the step between consecutive numbers.
• Reset period — see below.

When the counter resets

The counter is scoped by the reset period. Documents created in the same period share one counter, and a new period starts a new one.

Reset	Counter runs for	Template must contain
Never	One continuous series, forever	—
Yearly	A calendar year	{YYYY} or {YY}
Monthly	A calendar month	A year token and {MM}
Daily	A calendar day	A year token, {MM} and {DD}

The right-hand column is enforced, not advice. A yearly reset on a template with no year token would hand out INV-00001 again next January, so the engine refuses to save it and says why. There is no quarterly reset: {Q} is available as a date token you can print, but it does not scope a counter and it does not satisfy any of the requirements above.

Start value applies to the first number of a period, not to the next one

Once a counter is running, the next number is always the last one issued plus the increment. Raising the start value mid-year does not jump the sequence — it takes effect at the next reset, or on a document type that has never issued anything.

Date tokens use the day the number is issued

The date tokens read the server clock at the moment the number is minted. They do not read the date field on the document.

An invoice you enter today and date to last December is still stamped with this year’s tokens, and it draws from this year’s counter. Back-dating a document does not back-date its number. This is engine behaviour and therefore true in all three products, but it is most visible in Accounts, where back-dating a document into an open prior period is ordinary bookkeeping.

If your numbering has to line up with the document’s own date — a common statutory expectation for invoices — the practical answer is to keep entries current, not to rely on the format.

How the preview works

Each card shows a sample number that updates as you type. The sample is not rendered by the browser: the app sends the candidate configuration to the server and the server renders it with the same engine that mints live numbers, so the tokens, padding and literal text you see are exactly what a document will carry. The same round trip returns the validation errors, which is why the Save button stays disabled until the template is valid.

One thing the sample is not: a reading of the live counter. It renders the format at the start value, so the digits are 00001 (or whatever you set) rather than wherever the running counter has actually reached. Read it as this is the shape my numbers will take, not this is the next number.

Changing a format later

Numbers already issued are never rewritten. A document keeps the number it was given for life; the new format applies to the next document of that type and nothing else.

Editing the template — the prefix, the padding, which date tokens appear — leaves the counter exactly where it is. Change Q-{SEQ:6} to QUO-{YYYY}-{SEQ:6} after 412 quotes and the next one is QUO-2026-000413.

Changing the reset period is the one edit that moves the counter. The counter is scoped by period, so switching from never to yearly (or yearly to monthly, or any other change) puts it into a scope it has not been used in, and the very next document starts again at the start value.

Changing the reset period restarts the counter immediately

That is usually what you want — but only if the template distinguishes the new periods. If a template already carried {YYYY} while the reset was set to never, switching it to yearly restarts at 00001 inside a year that has already used those numbers. A numbered document carries a uniqueness constraint on its number in the database, so the repeat is refused and the save fails with an error rather than two documents sharing a number. Change the reset period at a period boundary, or raise the start value past the numbers already spent.

Can a number be reused, and can there be gaps?

Reused: no. Each number is claimed by a single atomic operation on the counter, so two people creating documents at the same instant cannot be handed the same one, without retry loops or lock contention. Beyond that, a numbered document’s number is constrained unique within the workspace — if a configuration change ever did produce a repeat, the database refuses the write and the save errors out. One document type is stricter than that: a CPQ sales agreement number is unique across every workspace rather than within one, so if two tenants both start their agreement series at the same value, the second one to save is rejected. Give sales agreements a format that is distinctive to the tenant, or a start value that will not meet another’s.

Gaps: yes, and they are expected. A number is claimed just before the document is written. Where the claim runs inside the document’s own transaction, an abandoned or failed save rolls the counter back and the number is handed to the next document. Where it does not, the number is spent and a gap is left in the series. Which paths do which varies by product — see the table below. Deleting a document also leaves its number spent; nothing reclaims it.

If your jurisdiction requires an unbroken invoice series, treat the gap as something you report on rather than something the numbering prevents.

A number you type yourself does not move the counter

The engine is not the only way a document gets its number. Several document types accept a number supplied by whoever creates the record, and use it as given.

Product	On a form somebody can fill in	Through the API only
Accounts	Fixed assets (Asset number) and retainer invoices (Retainer #) — each box is hinted leave blank and it is auto-numbered	Invoices
CRM	—	Quotes, sales orders
CPQ	—	An order created directly — the one path that does not use the configured format anyway

A supplied number does not advance the counter. Type FA-00042 on a fixed asset today and the counter is still sitting wherever it was; when it eventually reaches 42 the engine will mint FA-00042 again, and that save is the one that fails — with a duplicate-number error, on a document nobody connected to a number somebody typed months earlier.

This is the one numbering failure an administrator can walk into during ordinary use, and it is worth a house rule: leave the box blank and let the engine number the document, or keep hand-entered numbers plainly outside the configured series (a different prefix, or a block far above where the counter will ever reach).

What differs by product

The engine is shared. The adoption is not.

	CRM	CPQ	Accounts
Where the screen lives	Customize → Auto-numbering	Administration → Auto-numbering (under Data & Schema)	Settings → Auto-numbering
Document types on the screen	5	6	15
Number claimed inside the document’s transaction	On some paths only	On some paths only	On every path
Format change written to the audit log	Yes	No	Yes
Numbered documents the screen does not cover	Purchase orders, goods receipts, put-aways	Orders created directly; quote requests raised from a customer portal	—

The catalogue of document types is fixed in each product: you can change how a type is numbered, but you cannot add a type to the screen. A type you have never edited runs on a built-in default and the card is badged Default.

CRM

Five types — invoice, payment, quote, sales order and case — each defaulting to a prefix and six digits with no reset. The per-type defaults and the full screen walk-through are on Customization.

Numbers claimed inside the document’s transaction, where an abandoned save releases the number instead of spending it: a cloned quote, a quote converted to a sales order, an invoice raised from a sales order, and a payment recorded against an invoice. Numbers claimed outside it, where a failed save leaves a gap: a quote, sales order or invoice created from scratch, and a case — whether it is opened in the app or created by email-to-case.

CRM also numbers purchase orders, goods receipts and put-aways with a fixed built-in format that this screen does not reach.

CPQ

Six types — quote, sales order, sales agreement, subscription, contract and work order — most of them defaulting to a yearly reset with the year in the template. The defaults table is on Quotes & approvals.

Three things to know before you configure CPQ:

• An order created directly from Orders → New does not use the configured format. It is given a system-generated number instead. The sales-order format governs orders raised from a quote — see Orders & contracts.
• A quote requested from the customer portal does not use the configured format either. It lands in the same quote list as everything else, but with its own system-generated RFQ-… number rather than your quote format, so the list will show two number shapes side by side. See Portals for what a portal customer can raise. Agreements, subscriptions, contracts and work orders do use their configured format on every path.
• System Settings has an older Numbering tab offering a prefix and a starting number per document. Nothing reads it. It is a leftover from before the engine was adopted, and editing it changes no document’s number. Auto-numbering under Administration is the screen that works.

Numbers are claimed inside the document’s transaction on four paths: a quote converted to a contract, a subscription created from a quote, an order raised from a quote, and the mobile quote path. Elsewhere the claim is made first, so a failed save leaves a gap — including a quote created in the web app, a sales agreement, a contract created on its own, and a subscription created directly rather than from a quote. CPQ does not write a format change to its audit log, so if you need a record of who changed numbering, note it yourself.

Accounts

Fifteen types, from invoices and bills through payments, journal entries, credit notes, expenses, purchase orders, retainer invoices, fixed assets, estimates and sales orders. Defaults are a prefix and five digits with no reset. The full list and screen behaviour are on Platform & settings; one card, Debit note, is offered but unused because Accounts does not issue them.

Accounts is the cleanest adoption of the three. Every number is claimed on the same transaction that writes the document — including numbers minted by background work such as dunning and recurring invoices — so a failure rolls the counter back with the document and gaps come only from deletions, not from failed saves. Format changes are recorded in the Activity Log.

Who can change numbering

Numbering is administrator metadata, and each product gates it through roles and permissions:

• CRM — saving a format requires the customization permission, the same grant that governs the rest of Customize. Viewing the current formats needs only workspace sign-in.
• CPQ — reading and saving are both gated on the numbering surface’s own permission.
• Accounts — gated on a permission for the numbering route group. Because that group was added after the roles were first seeded, a role that ought to have it may not; see Implementation verdict for the pattern and the fix.

As everywhere in the suite, the API is the boundary and the menu is a courtesy: a hidden menu item is not an access control. A few administrative capabilities across these products are not governed by the permission matrix at all, so workspace sign-in is what really grants them — give an account only to someone you would trust with the workspace’s configuration.

Where the detail lives

• CRM — Customization — the Auto-numbering screen, its five document types and their defaults.
• CPQ — Quotes & approvals — the six types, their defaults, and the sales-order caveat.
• Accounts — Platform & settings — the fifteen types and how numbering sits with the rest of Settings.
• Customization — the wider admin surface this screen belongs to.
• Roles & permissions — who gets to change any of it.