Invoice numbers tell any member roughly how much business the deployment does #60

New Issue

2026-09-21T07:18:18Z

cgalo5758 commented

2026-09-21 07:18:18 +00:00

The question

Platform invoice numbers come from a single counter across the whole deployment, formatted as four digits. A member holding two invoices can read the deployment's total volume from the first and its rate from the difference, the way wartime analysts estimated production from serial numbers. Numbering cannot simply be randomized: sequential, unique and gapless numbering is a tax requirement in many jurisdictions. So which numbering scheme does the console use?

What depends on the answer

What a number reveals, and how numbers already issued are treated, since an issued number is immutable and any new scheme starts at a cutover rather than rewriting history.

Options known so far

Start the sequence at an arbitrary number: hides the absolute total, not the rate between two invoices. Cosmetic.
A sequence per year, reset each year: a leak reveals at most the current year's volume. The common recommendation.
A sequence per billing account: a member learns only their own count, and the guidance that is strictest about gapless numbering explicitly allows several ranges as long as each is consistent within itself. Every organization already has a billing account, so the ranges exist.

Per billing account fits this model best and keeps the numbers short.

Decided when

The billing model names the scheme, says what happens to numbers issued under the old one, and the assignment code implements exactly that.

Migrated from status/issues.md at b7a0e15

## The question Platform invoice numbers come from a single counter across the whole deployment, formatted as four digits. A member holding two invoices can read the deployment's total volume from the first and its rate from the difference, the way wartime analysts estimated production from serial numbers. Numbering cannot simply be randomized: sequential, unique and gapless numbering is a tax requirement in many jurisdictions. So which numbering scheme does the console use? ## What depends on the answer What a number reveals, and how numbers already issued are treated, since an issued number is immutable and any new scheme starts at a cutover rather than rewriting history. ## Options known so far - Start the sequence at an arbitrary number: hides the absolute total, not the rate between two invoices. Cosmetic. - A sequence per year, reset each year: a leak reveals at most the current year's volume. The common recommendation. - A sequence per billing account: a member learns only their own count, and the guidance that is strictest about gapless numbering explicitly allows several ranges as long as each is consistent within itself. Every organization already has a billing account, so the ranges exist. Per billing account fits this model best and keeps the numbers short. ## Decided when The billing model names the scheme, says what happens to numbers issued under the old one, and the assignment code implements exactly that. Migrated from status/issues.md at b7a0e15

cgalo5758 added the

kind

design

area/billing privacy labels 2026-09-21 07:18:18 +00:00

cgalo5758 commented

2026-09-28 04:32:05 +00:00

Decided and built, so closing. The single deployment-wide counter this issue describes has been replaced.

Scheme. The identifier policy in design/ specifies the invoice number: a gapless counter per billing account, incremented in the transaction that issues the invoice, never a sequence. A member can count only their own invoices.
Built. internal/db/migrations/00013_invoice_numbers.sql and AssignNextInvoiceNumber implement it. Numbers issued under the deployment-wide counter are kept verbatim and never renumbered.
Compliance. HMRC asks for "a sequential number based on one or more series which uniquely identifies the document" (VAT Notice 700 §16.3.1); the EU VAT Directive, art. 226(2), uses the same words. A series per billing account is one such series.

Two points remain outside this issue:

Stripe's own number is what appears on Stripe's invoice PDF, hosted page and receipt, and the console shows it beside its own. It follows the Stripe account's numbering setting. "Sequentially for each customer" reveals nothing beyond the member's own count. "Sequentially across your account" reveals the account's volume, and it is Stripe's default for EU and UK accounts, which Stripe says "typically require account level sequencing". docs/stripe.md will name the setting and leave the choice to the operator and their accountant.
The platform's number is not unique across the issuer. "0001" identifies a document only together with its billing account. If the platform ever prints its own number on an invoice it issues, the number needs a series identifier, such as an account prefix. A note for the identifier policy goes upstream.

Decided and built, so closing. The single deployment-wide counter this issue describes has been replaced. - **Scheme.** The identifier policy in `design/` specifies the invoice number: a gapless counter per billing account, incremented in the transaction that issues the invoice, never a sequence. A member can count only their own invoices. - **Built.** `internal/db/migrations/00013_invoice_numbers.sql` and `AssignNextInvoiceNumber` implement it. Numbers issued under the deployment-wide counter are kept verbatim and never renumbered. - **Compliance.** HMRC asks for "a sequential number based on one or more series which uniquely identifies the document" (VAT Notice 700 §16.3.1); the EU VAT Directive, art. 226(2), uses the same words. A series per billing account is one such series. Two points remain outside this issue: 1. **Stripe's own number** is what appears on Stripe's invoice PDF, hosted page and receipt, and the console shows it beside its own. It follows the Stripe account's numbering setting. "Sequentially for each customer" reveals nothing beyond the member's own count. "Sequentially across your account" reveals the account's volume, and it is Stripe's default for EU and UK accounts, which Stripe says "typically require account level sequencing". `docs/stripe.md` will name the setting and leave the choice to the operator and their accountant. 2. **The platform's number is not unique across the issuer.** "0001" identifies a document only together with its billing account. If the platform ever prints its own number on an invoice it issues, the number needs a series identifier, such as an account prefix. A note for the identifier policy goes upstream.

cgalo5758 closed this issue

2026-09-28 04:32:06 +00:00

cgalo5758 referenced this issue from a commit

2026-10-02 00:49:58 +00:00

Read invoices back from Stripe and archive the change

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: wiki-cafe/member-console#60