Prorating Usage-Based Line Items Mid-Cycle
Prorating a flat fee is arithmetic: charge for the days used at the old price and the days remaining at the new one. Prorating a metered line is a modelling question, because the customer has already consumed part of an allowance that the new plan defines differently. This guide sits under Proration Logic & Calculations and covers the choices and their consequences.
The situation is ordinary. A customer on a plan including 10,000 API calls has used 7,000 by the fifteenth of the month, then upgrades to a plan including 50,000. What is their allowance for the rest of the period? Is the 7,000 already spent against the new allowance, or does the new plan start fresh? Both answers are defensible, both are implementable, and picking one without deciding is how invoices become inexplicable.
The deciding principle should be that the customer is never worse off for upgrading. Any model that can make an upgrade increase this period’s bill relative to not upgrading will eventually produce a support ticket that is impossible to answer well.
Trade-offs
| Model | Allowance for the period | Tier progress | Customer intuition | Complexity |
|---|---|---|---|---|
| Split the period into segments | Prorated per segment | Resets per segment | “Two half-months” | Medium |
| Carry the counter forward | New plan’s full allowance | Continues | “I upgraded, I get more” | Low |
| Prorate the new allowance only | Blend of both | Continues | Hard to explain | Medium |
| Reset everything at the change | New plan’s full allowance | Resets | Generous, can be gamed | Low |
Most self-serve products should carry the counter forward. It is simpler, it is always favourable to the customer on an upgrade, and the revenue difference is small relative to the support cost of the alternative. Splitting earns its complexity where allowances are large enough that the difference is material — typically enterprise contracts, where the customer’s own finance team will check the arithmetic.
Step-by-Step Implementation
1. Prorate the allowance by elapsed time
from decimal import Decimal, ROUND_HALF_UP
def prorated_allowance(full_allowance: int, segment_seconds: int, period_seconds: int) -> int:
"""Allowance for a partial segment, rounded once."""
share = Decimal(segment_seconds) / Decimal(period_seconds)
return int((Decimal(full_allowance) * share).quantize(Decimal("1"), rounding=ROUND_HALF_UP))Use seconds rather than days. A plan change at 14:00 on a 30-day period is not a whole-day boundary, and day-granularity rounding produces allowances that differ from the flat-fee proration on the same invoice — an inconsistency customers notice.
2. Decide the tier reset rule
Tiered pricing compounds the question: if the first 1,000 calls are free and the next 9,000 cost $0.01, does the tier ladder restart at the plan change? Under the split model it must, because each segment is independently rated. Under carry-forward it must not, or a customer could upgrade repeatedly to re-earn a cheap first tier.
def rate_segment(usage: int, allowance: int, tiers: list[tuple[int, Decimal]],
prior_usage: int = 0) -> Decimal:
"""Rate one segment. prior_usage > 0 continues the tier ladder rather than resetting it."""
billable = max(0, usage + prior_usage - allowance)
total, remaining, consumed = Decimal(0), billable, prior_usage
for upper, unit_price in tiers:
room = max(0, upper - consumed)
take = min(remaining, room)
total += Decimal(take) * unit_price
consumed += take
remaining -= take
if remaining == 0:
break
return total3. Rate each segment against its own price version
4. Attribute events to segments by event time
An event’s segment is determined by when the usage occurred, not when it was ingested. That distinction matters because late-arriving events can land after a plan change and still belong to the earlier segment.
5. Render both segments on the invoice
API calls (1–15 Mar, Starter)
7,000 used · 5,000 included · 2,000 × £0.010 = £20.00
API calls (16–31 Mar, Growth)
18,000 used · 25,000 included = £0.00A single blended line for a period containing a plan change cannot be checked by the customer, which means every question about it becomes a support conversation with a manual recomputation.
Downgrades, and Why They Are Harder
Everything above assumes an upgrade. Downgrades introduce a case with no universally fair answer: the customer has already consumed more than the new plan includes.
Under the split model this resolves cleanly — the first segment’s usage is rated against the first segment’s allowance, and the second segment starts with its own smaller prorated allowance. The customer is not retroactively penalised for usage that was within their allowance at the time, which is the property that matters.
Under carry-forward it does not resolve cleanly at all. A customer who used 7,000 calls on a plan including 10,000, then downgrades to a plan including 5,000, is suddenly 2,000 over an allowance they never agreed to. Charging for that overage is indefensible: the usage was included when it happened. The workable rule is that carry-forward applies to upgrades and the split model applies to downgrades, which is asymmetric but always favourable to the customer and easy to state.
That asymmetry is worth writing into the product documentation explicitly, because it is the kind of rule that looks arbitrary until the reasoning is given. “Upgrades give you the larger allowance for the whole period; downgrades only apply to the remainder of the period” is a sentence customers accept immediately.
A related decision is whether a downgrade mid-cycle is permitted at all for metered plans. Many products schedule downgrades to the period end precisely to avoid this, using the phase model described in handling scheduled plan changes. That is the simplest correct answer, and it is worth choosing before building the split-model machinery to support something you would rather not offer.
Explaining It on the Invoice and in the Product
A metered proration that is arithmetically correct and visually opaque still generates support tickets, so the rendering deserves as much attention as the calculation.
Show the segments as separate lines with their date ranges, plan names, allowances, and usage. The customer’s mental model is “I was on one plan and then another”, and an invoice that mirrors that model can be checked without help. A single line labelled “API usage” for a period containing a plan change cannot.
Show the allowance, not just the overage. A line that reads “18,000 used, 25,000 included, £0.00” tells the customer they are within their allowance and reassures them the upgrade worked; a line showing only a zero charge tells them nothing and occasionally reads as a billing error.
Preview the effect before the change is made. When a customer selects a new plan mid-cycle, showing what this period’s usage line will look like afterwards removes the main uncertainty in the decision — and for upgrades, it is usually a persuasive number, because the new allowance covers usage that was about to become overage.
Keep the in-product usage meter consistent with the invoice. If the dashboard shows usage against the new allowance while the invoice splits the period, the two will disagree and the customer will trust neither. Whichever model you chose, the meter should reflect it, including the segment boundary if you split.
Finally, document the rule in the billing help pages using the customer’s words rather than the accounting ones. Two sentences covering upgrades and downgrades will deflect more tickets than any amount of invoice detail, because most customers want to know the principle rather than to audit the arithmetic.
Verification & Testing
Test the asymmetry directly: assert that upgrading mid-period never produces a higher total for the period than not upgrading, across a grid of usage levels. This is a property test rather than an example test, and it catches the entire class of “upgrade penalised the customer” bugs in one assertion.
Test allowance proration against the flat-fee proration on the same invoice with the same change instant, and assert they use the same elapsed-time basis. A metered line prorated by whole days beside a flat line prorated by seconds is an inconsistency that a careful customer will find.
Test event attribution across the change boundary using event time, including an event that occurred before the change but was ingested after it. Assert it lands in the first segment and is rated against the old rate card.
Gotchas & Production Pitfalls
- Tier ladder reset on every change. Lets a customer re-earn cheap first tiers by upgrading and downgrading, which is a pricing exploit rather than an edge case.
- Allowance prorated by days, fee prorated by seconds. Produces two internally inconsistent lines on one invoice.
- Events attributed by ingestion time. Puts late events in the wrong segment and rates them against the wrong plan.
- A single blended metered line. Cannot be verified by the customer and cannot be explained by support without a manual recomputation.
- Downgrades treated like upgrades. Retroactively bills usage that was included under the plan in force at the time.
Frequently Asked Questions
Which model should a new product choose? Carry-forward for upgrades, split for downgrades, and schedule downgrades to the period end where possible. That combination is simple, always favourable, and avoids most of the complexity.
Does this change how usage is stored? No, only how it is attributed and rated. Storing raw events with event time, as the metering pipeline already does, provides everything both models need.
What about annual plans with monthly allowances? Treat each monthly allowance window as the period for this purpose. The plan change still splits the current window; earlier windows are closed and unaffected.
How does this interact with commitments? A negotiated commitment draws down independently of plan allowances, so a mid-term plan change affects the included allowance but not the drawdown balance. Keep the two mechanisms separate on the invoice as well as in the code.