Product catalogue versioning: plan versions, snapshots, grandfathering
You raise the price of your "Team" plan on 1 October. In November a customer queries a September invoice, and support issues a credit note for one seat. The system looks up the plan's price, finds the new October price and puts it on the credit note. The credit note no longer matches the original invoice, and nobody can explain the amount without querying the database.
The cause is almost always the same model: a plan has a price, and that price is edited when needed. This article describes a versioning model for the product catalogue in which every invoice can be traced, years later, to exactly the pricing logic that produced it. How to roll out price changes operationally without a deploy is covered in price changes without deployment.
Plan and plan version are separate objects
The plan is what sales and marketing sell: "Team", "Business", "Enterprise". The plan version is the concrete pricing logic at a point in time: currency, interval, price per seat, included quantities, unit price above them, tiers, tax category. A plan has many versions; a subscription points to exactly one.
Plan id, code ("team"), name
PlanVersion id, plan_id, version, currency, interval,
sellable_from, sellable_until, tax_category,
components[]
Component type (seat | usage | flat), meter_version_id,
unit_price, included_quantity, tiers[]
Subscription id, customer_id, plan_version_id,
term_start, term_end, renewal_policy
InvoiceLine invoice_id, plan_version_id, service_period,
pricing_snapshot {unit_price, included_quantity, tiers, meter_version}
A published plan version is immutable. To change a price, you create a new version. It sounds like red tape, but it settles in advance every later argument about which price applied when.
Two periods: sellable and contracted
A plan version has a sales window (sellable_from, sellable_until). It decides which version a new customer gets at checkout today. The subscription, independently, has a contract term. A customer who signed an annual contract on version 1 in June stays on version 1 until the term ends, even if only version 2 has been on sale since October.
Keeping these apart prevents the most common mistake: treating a new price list going live as if it changed every running contract. Whether and when existing customers move to the new version is a commercial decision. It has to be recorded on the subscription, not implied by "the current price applies".
An example: same usage, two versions
A "Team" plan with a seat price and API calls above an included quantity (net amounts, made up for the example):
| Version 1 (to 30 Sep) | Version 2 (from 1 Oct) | |
|---|---|---|
| Price per seat per month | €30.00 | €35.00 |
| Included API calls | 10,000 | 20,000 |
| Price per call above that | €0.002 | €0.0015 |
| Customer: 20 seats, 30,000 calls | €600 + €40 = €640.00 | €700 + €15 = €715.00 |
A version 1 customer's September invoice comes to €640. If the credit note from the opening example looks up the price via the plan instead of the version, it uses €35 rather than €30 per seat. The invoice line's snapshot, though, holds unit_price: 30.00, and the credit note copies exactly that value.
The usage side shows why the whole parameter set has to be versioned. Version 2 costs more per seat but less on usage, thanks to the larger included quantity. If you version only the seat price and leave the included quantity on the plan, you produce invoices that match neither version.
The invoice line stores its pricing parameters
In theory a reference to plan_version_id is enough if versions really are immutable. In practice, databases get migrated, catalogues get tidied up and versions get edited by mistake. So at finalisation the invoice line also copies the parameters it used into a snapshot.
For German companies there's a compliance reason too. Germany's bookkeeping rules, the GoBD, require records to be traceable and unalterable, and invoices must be kept for eight years. A tax auditor recalculating an invoice from two years ago needs the prices that applied then, not today's.
The same goes for descriptions. If marketing renames "Team" to "Team Pro", the text on old invoices must not change. The snapshot therefore also holds the line description as it appeared on the document.
Meters need versions too
For usage components the price is only half the logic. The other half is what gets counted. A meter called api_calls seems unambiguous until someone decides that requests failing with a 5xx no longer count, or that retries from the same client are merged.
That kind of change is a price change even if no euro amount moves: the same customer pays a different amount for the same usage. So it needs a new meter version with a cut-over date. Events before the cut-over are counted under the old rule, events after it under the new one. What counts is the event's usage time, not its arrival time, or a late event gets counted under the wrong rule. How to keep usage time and arrival time apart is covered in idempotent usage event processing.
Moving existing customers to a new version
There are three ways to move existing customers, and the subscription has to record which one applies:
- Grandfathering: the customer stays on their version until they switch or the contract ends.
- Switch at renewal: the new version applies from the next term. This is the usual route for annual contracts and can be paired with a notice period.
- Immediate switch: the subscription changes mid-term. That needs a contract amendment with an effective date, proration and possibly a credit note for periods already billed.
Option 3 is where the model pays off. The invoice run produces two lines: one on version 1 with a service period up to the effective date, one on version 2 from that date. Each line carries its own snapshot. If you report under IFRS, agree such changes with your finance team as well, because IFRS 15 has its own rules for contract modifications.
What triggers a new version and what doesn't
Not every catalogue change needs a new version. A practical split:
| Change | New version? |
|---|---|
| Price, currency, billing interval | yes |
| Included quantity, tier boundaries, minimum quantity | yes |
| Meter definition (what is counted) | yes, new meter version |
| Tax category | yes, agreed with finance |
| Marketing copy on the website | no |
| Translated plan name for new invoices | no, old invoices keep their snapshot |
Also decide who may publish a version. Product owns prices; finance owns tax category and revenue treatment. A version with tax or revenue consequences should only become sellable once both have signed off.
Test new versions against real contract states: a customer in the middle of an annual term, one with a pending direct debit return, one with late usage events from the previous month. Kontier brings the product catalogue, contracts and usage events together in one billing flow; the usage-based billing page shows how usage components are modelled there.
Not tax or legal advice. This post describes the law and common practice in general terms. For your own case, ask your tax adviser. As of: