Systems and records
Subscription billing transition dataset: save the proration choice
By SourceX Editorial · Reviewed by Noah Loul ·
10 sections
Short answer
A subscription billing transition dataset should store, for every mid-period change, the requested, effective and invoice dates, the proration and timing rule actually applied, the lines it produced and every correction linked to its original. In the three of four public billing APIs we read that let the caller set proration per change, no stored subscription or change resource keeps that choice; it survives only on invoice lines or in request logs.
System export
Subscription billing
Key takeaways
- Keep the requested, effective and invoice dates as three fields; billing systems let all three differ.
- In Chargebee, Paddle and Recurly the caller chooses proration per change, and none of their stored subscription or change resources has a field for it.
- Of 11 timing parameters across four plan-change requests, 4 have a same-named stored field; of 3 proration parameters, none.
- Six labels cover the decision: prorate now, prorate on the next invoice, defer to renewal, full charge with no credit, hold and escalate.
- Routine proration credits, pre-2017 Recurly lines without a rate and no-credit seat cuts are hard negatives, not errors.
What does a mid-period subscription change force someone to decide?
A plan change that lands inside a period the customer has already been billed for forces three choices: when the change takes effect, what happens to the unused part of the old plan, and when the difference is invoiced. An upgrade on day 12 of a monthly period can be charged now for the remaining days, carried to the next invoice, charged in full, or deferred to renewal. A downgrade can earn a credit for unused time, earn nothing, or wait for the term to end.
Most of the time a billing engine makes these choices from configured defaults. The decisions worth teaching an AI system are the ones where the default is not the right answer: the change is asked to take effect in a month whose books are closed, the invoice for the overlapped period is under dispute, an earlier change in the same term was applied without proration, or the contract only allows changes at renewal. There the right answer is a hold, an escalation, or a deferral, and the record has to show why.
A subscription billing transition dataset is the set of change records that teaches or tests that decision. Each case holds the request, the effective and invoice dates, the rule actually applied, the invoice lines it produced, and every later correction linked back to what it corrected. Without the rule and the links, the same lines can be read as a correct proration or as a billing error.
Four billing APIs: the proration choice is made per change, not stored with it
In three of the four public billing API definitions we read, the caller chooses proration for each change, and none of their stored subscription or change resources keeps that choice. We read the plan-change operation of Chargebee (its OpenAPI specification at commit 06f6ff8), Paddle (its Node SDK types at commit 6a01ef4), Recurly (API version v2021-02-25, in its Python client at commit eef8d3c) and Square (its API specification at commit 0689c90), and checked each timing or proration parameter against the fields of the resource the vendor stores and returns.
Across the four requests, 11 top-level parameters set timing, and 4 of them have a same-named field on the stored resource: Chargebee's changes_scheduled_at, Paddle's next billed date and scheduled change, and Recurly's next_bill_date. Three parameters set proration: Chargebee's prorate flag, Paddle's proration billing mode with five values (prorated immediately, prorated next billing period, full immediately, full next billing period, do not bill) and Recurly's proration settings, which choose charge and credit treatment separately among full amount, prorated amount and none. None of the three has a field on the stored subscription or change. Square's swap request carries neither: it schedules a plan swap action with an effective date, and a plan variation carries a can_prorate flag.
The choice survives only indirectly. All three vendors that let the caller choose proration mark it on invoice or transaction lines: Chargebee's line items carry a proration_mode with four values and a reference_line_item_id, Paddle's transaction lines carry a proration rate and billing period, and Recurly's line items carry a proration_rate, start and end dates and links to the previous line and the original invoice. Recurly's own definition notes that proration rates exist only for line items created after March 30, 2017, so an older line with no rate is not evidence that nothing was prorated.
Chargebee's definition adds the reason a stored default is not enough: when prorate is not sent, the value configured in the site settings applies. A dataset therefore needs either the request log or the settings history for the date of each change. The comparison, parameter by parameter:
| API definition | Timing parameters, stored | Proration parameter | Proration stored | Line evidence |
|---|---|---|---|---|
| Chargebee, update subscription for items | 7, of which 1 stored | prorate (true or false; site setting when omitted) | No | proration_mode, service dates, reference line |
| Paddle, update subscription | 2, both stored | proration billing mode (5 values) | No | proration rate and billing period |
| Recurly, create subscription change | 2, of which 1 stored | proration settings: charge and credit (3 values each) | No | proration_rate, dates, previous line, original invoice |
| Square, swap plan | 0 | None in the request | Not applicable | Not read |
Three dates, one rule and a chain: the fields each change record needs
Each change record needs three dates kept apart, the rule that was resolved at the time, and the chain of documents it produced. The three dates are when the change was requested, the date it was made effective, and the date the resulting invoice carries, because systems allow all three to differ. Chargebee's definition, for example, lets a change be backdated through changes_scheduled_at when backdating is enabled and, among other conditions, the date is on or after the current term start, and lets an invoice date be set up to one calendar month in the past, with taxes computed on the tax configuration as of that invoice date.
At a glance
Three dates, one rule and a chain: the fields each change record needs
The chain matters for tax as well as for training. Under Article 219 of the EU VAT Directive, a document that amends an invoice and refers specifically and unambiguously to the initial invoice is treated as an invoice, so a credit for an overlapped period should carry its link to the invoice it corrects. The fields for each change:
- Change request: who asked, through which channel, the requested effective date and the plan, price or quantity asked for.
- Applied timing: immediately, next billing date, term end or a specific date, as resolved by the system, with the effective date it recorded.
- Proration rule applied: the per-change parameter if sent, otherwise the account or site setting in force that day, and its source.
- Invoice date and accounting period: the date on the resulting document and whether that period was open or closed when it was issued.
- Lines produced: each line's service period, amount, proration marker or rate, and the line or invoice it references.
- Corrections: credit notes, voids and adjustments, each with its reason code, its link to the original document and the gap in days.
- Prior changes in the same term: whether any is pending, uninvoiced or applied without proration.
- Payment state of the overlapped invoice: paid, open, in dunning or disputed, as of the change date.
- Approver and note: who confirmed an exception and the reason given, kept as a category plus the free text.
Six labels for an overlapping change, tested in a fixed order
The label set is the decision space the APIs expose plus two human routes: prorate now, prorate on the next invoice, defer to renewal, full charge with no credit, hold and escalate. Every case gets exactly one, and the rule is applied in a fixed order so a reviewer can recompute it.
First match wins. A change whose effective date falls before the earliest open accounting date is escalated, because it touches closed books. A change against a disputed invoice for the overlapped period is held. A change that follows an earlier change in the same term that is unreconciled or was made without proration is held, because Chargebee's definition shows the earlier choice can silently change the later result: a prorated change made mid-term creates no credits when an earlier change in the same term had prorate set to false, the term was not changed, and only items or prices were updated. A contract that allows changes only at renewal defers the change. A reduction under terms that give no credit for unused time gets a full charge with no credit. An increase under terms that collect at the change is prorated now. Everything else is prorated on the next invoice.
These labels describe billing, not revenue. Revenue accounting treats the same change as a contract modification: IFRS 15 sorts modifications into a separate contract, a termination of the old contract and creation of a new one accounted for prospectively, or part of the original contract with a cumulative catch-up adjustment. That call belongs to the finance team and deserves its own field.
Eight changes and the label each one earns (illustrative casebook)
The cases are invented to reach every label and the traps between them, and a script assigns each label from the rule above. Two of them would pass a naive check: B2 shows no credit for removed seats and looks like an error, and B6 shows a correct-looking proration that the system will not credit because of the earlier change. The eight changes:
| Case | Change | Label | Rule that decided it |
|---|---|---|---|
| B1 | Upgrade on day 12 of a monthly period; period invoice paid | Prorate now | Increase, terms collect at the change |
| B2 | Seats cut from 40 to 30 on day 20; terms give no credit for removed seats | Full charge, no credit | Reduction under a no-credit term |
| B3 | Annual plan downgrade in month 5; changes allowed only at renewal | Defer to renewal | Contract timing |
| B4 | Upgrade asked to take effect 45 days back; that month's books are closed | Escalate | Effective date before the open period |
| B5 | Plan change while the overlapped invoice is in a card dispute | Hold | Disputed overlapped invoice |
| B6 | Second change this term; the first was applied without proration | Hold | Earlier change in the same term |
| B7 | Seats added on day 8; extra seats billed on the next invoice | Prorate on next invoice | Default route |
| B8 | Monthly downgrade on day 15; terms credit unused time | Prorate on next invoice | Default route |
Hard negatives: corrections that are not errors
Many corrections after a plan change are the change working as designed, and a dataset that calls every credit an error teaches a model to flag routine billing. Collect these explicitly and label them by the rule they followed:
- Proration credits for unused time, which Chargebee credit notes can carry under the reason code subscription_change (a field its definition marks deprecated in favor of configurable codes) and Paddle records as an adjustment of type proration.
- A change that produces no credit because an earlier change in the same term was applied without proration, the Chargebee constraint above.
- Recurly line items from before March 30, 2017 with no proration rate, where the field did not exist yet.
- Backdated invoices whose tax differs from today's rate because tax was computed on the configuration as of the invoice date.
- A forced term reset on a change to a plan with the same billing period, which starts the term from the change date so every later period boundary moves (Chargebee's force_term_reset).
- Seat reductions under terms that give no credit, which look like a missing refund.
- A plan swap on a platform whose swap request offers no proration choice and schedules the swap as a dated action, so the overlap may never arise.
Outcome labels: how a team learns the change was billed right
The outcome of a change is known only later, from what happened to the documents it produced inside a fixed observation window. A clean outcome means the resulting invoice was paid and no correction referenced the change within the window. A corrected outcome means a credit note, void or adjustment later referenced the change's lines, with its reason code saying whether it was an error fix or a routine follow-on. A disputed outcome means a chargeback or a formal dispute named the invoice. Changes younger than the window are open, not clean.
The correction history is what turns these into labels, so it has to be complete. Keep every version of a corrected document rather than its final state, keep the link from each correction to the line it corrects, and record the gap in days. A correction 3 days after a change says something different from one 90 days later, after a quarter closed.
Grade a system on the label and on the documents it would have produced. Two systems can both choose prorate now and still differ on which period the credit covers. For evaluation, hold out the most recent months, because price lists, proration settings and contract templates change over time and a random split hides that drift.
What a billing system's records can show, and where they stop
A billing system's records can show the lines, the service periods, the proration markers and, in the better designs, the links from each correction to its original; they usually cannot show the choice that was sent with the request, the settings in force on the day, or why a person overrode the default. Request logs, audit events or webhook archives fill the first gap; a settings history fills the second; support tickets and emails hold the third, and they carry the customer's own words about what they asked for.
Revenue records are a separate source. If the finance team accounts for a change as a contract modification, its schedule shows the treatment chosen, which can differ from the billing route and should be joined by contract and date rather than copied into the billing label.
Before licensing, the billing records need the usual separation. Customer names, emails, addresses and payment details are not needed to learn a proration decision and should be removed or replaced with stable tokens; contract terms quoted in tickets may be confidential to the customer; and de-identification alone does not give the company the right to license its records. Counsel should review the specific terms, and accounting or tax specialists should review any rule that touches closed periods or VAT.
Requesting subscription change histories through SourceX
SourceX does not keep datasets on a shelf; it sources them on request, so a request for subscription change histories starts from your task. Its data request form asks for the domain and source systems, approximate volume, format, geography, language, historical timeframe, licensing requirements including permitted use, de-identification requirements, and any additional specifications.
Put the parts that make these records usable into the specification: the three dates per change, the applied proration rule or the request log that shows it, line-level links to corrected documents, the observation window for outcomes, and an acceptance test such as a recent-months holdout scored per label with the six labels or your own. A likely supplier is a subscription business whose billing system keeps line-level proration and correction links and whose request logs or settings history survive; whether a given company has them, can license them and passes your test is checked during review, not assumed.
How the API definitions were read
We cloned four public repositories at pinned commits on October 28, 2026 and read only their definition files with our own script, bin/xs0816_change_fields.py: Chargebee's spec/chargebee_api_v2_pc_v2_spec.json (commit 06f6ff8), Paddle's TypeScript types in the Node SDK, which the files say are autogenerated (commit 6a01ef4), Recurly's openapi/api.yaml for API version v2021-02-25 (commit eef8d3c) and Square's api.json (commit 0689c90). The operations read were fixed before counting: Chargebee's update subscription for items, Paddle's update subscription body, Recurly's subscription change create and Square's swap plan request; the stored resources were Chargebee's Subscription, Paddle's subscription response, Recurly's SubscriptionChange and Subscription, and Square's Subscription and SubscriptionAction.
Only top-level request properties were read. Names were split into word tokens on underscores and camelCase, and a parameter counted as proration if a token starts with prorat, or as timing if its tokens contain a listed phrase such as change option, end of term, effective, scheduled, invoice immediately, invoice date, next bill, next billed, term reset, billing alignment, timeframe or anchor, matched as whole tokens so that revenue_schedule_type is not counted. A parameter counted as stored when a property with the same name, ignoring case and underscores, appears on the stored subscription or change resource. Line evidence counts line-item properties with a token starting prorat or containing date from, date to, start date, end date, billing period, reference line, original line, previous line or credit reason, plus the fields of Paddle's line proration object; Square's lines were not read because its swap request has no proration parameter. The script prints every property it did not count.
Limits: definitions describe what an API accepts and returns, not what a given company configures or logs. A same-name test can miss a stored field with a different name, and a company may keep request logs that hold the choice. The four vendors were chosen because their definitions are public on GitHub, not as a market sample.
Frequently asked questions
What is a subscription billing transition dataset?
It is a set of subscription change records, each with the request, the effective and invoice dates, the proration rule actually applied, the invoice lines produced and every later correction linked to its original. It trains or tests a system that decides how a mid-period change should be billed, including when to hold or escalate.
Why is the account's proration setting not enough?
Because the choice can be made per change and the default can change over time. In Chargebee's API definition, the site setting applies only when the request omits the prorate parameter, and in the three APIs we read that offer the choice, no stored subscription or change resource keeps it.
Is every credit note after a plan change a billing error?
No. Proration credits for unused time are routine, and some systems label them, for example Chargebee's subscription_change credit note reason and Paddle's proration adjustment type. Label a correction as an error only when its reason code or reviewer finding says so.
How should a backdated subscription change be labeled?
If the effective date falls before the earliest open accounting date, escalate it, because it touches closed books and possibly tax computed as of an earlier date. Keep the requested, effective and invoice dates as three separate fields so the backdating is visible.
Does the billing label decide the revenue treatment?
No. IFRS 15 sorts a contract modification into a separate contract, a prospective termination and new contract, or a cumulative catch-up, and that is a finance decision. Store it as its own field and join it to the billing record by contract and date.
Sources
- Chargebee's OpenAPI specification defines the update-subscription-for-items parameters (change_option, prorate with a site-setting default, backdating rules, invoice_date limits), the Subscription fields, invoice line proration_mode and credit note reason codes. Source
- Paddle's Node SDK types define the update-subscription body (proration billing mode with five values, next billed date, scheduled change), the stored subscription fields and transaction line proration. Source
- Recurly's OpenAPI file (v2021-02-25) defines the subscription change timeframe and proration settings, the stored SubscriptionChange fields and line item proration_rate, dates and links. Source
- Square's API specification defines the swap-plan request, the SWAP_PLAN subscription action with an effective date and the plan variation can_prorate flag. Source
- IFRS 15 paragraphs 20 and 21 classify a contract modification as a separate contract, a termination and new contract, or part of the original contract with a cumulative catch-up. Source
- Article 219 of the EU VAT Directive treats a document that amends and refers specifically and unambiguously to the initial invoice as an invoice. Source
- SourceX's data request page says datasets are sourced on request, not held in stock, and lists the request fields used in the closing section. Source
Tell us what data you need
Share scope, volume, format, timing and licensing needs. Datasets are sourced on request.