Stripe Proration

Not a discount, and the difference is enforced

The clearest evidence that a proration is not a discount is that Stripe will not let you discount one.

The invoice line item object carries a discountable flag, documented as "If true, discounts will apply to this line item. Always false for prorations." The coupons documentation states the consequence directly: "You can't discount proration line items further on the invoice that's generated."

This is not the same as saying prorations ignore your pricing. Stripe is precise about where the discount does apply: "When calculating proration credits or debits, Stripe uses the subscription's discounted price, not the original price. However, no additional discounts are applied to the proration line items themselves because they're marked discountable=false."

So the discount is inside the number and cannot be applied to it a second time. That distinction matters when an invoice mixes both kinds of line. Stripe notes that a discount on an invoice containing prorations and non-prorations "only apply to the invoice items and invoice line items that aren't prorations". A customer on a 20 percent coupon who upgrades mid-cycle sees the coupon reflected in how the proration was computed, and sees no coupon line against the proration itself.

The practical version: if you are reconciling a discount total against invoice lines, proration lines will never carry a discount amount, and that is correct rather than a gap.

A proration covers a different window than the line next to it

Every Stripe invoice line has a period, and a proration's period is defined differently from a subscription's.

For subscription lines, Stripe says the period "is the subscription period". For prorations, it "starts when the proration was calculated, and ends at the period end of the subscription". Those are not the same window, and they can appear on the same invoice.

So a single invoice can carry a subscription line covering a full upcoming month and a proration line covering eleven days of the month currently in progress. The document has one date on it. Its lines describe two different spans, one of which is partly in the past.

This is the detail that makes prorations a period-boundary problem rather than a pricing problem. The credit half of a proration pair restates a period you have already closed books on, if the change lands after your close. The amount is small, the accounting question is not: revenue recognised last month is being adjusted by a line dated this month.

Ordering compounds the confusion. Stripe documents the invoice line sort as pending invoice items, including prorations, in reverse chronological order first, then subscription items, then invoice items added after creation. That is why a proration commonly appears above the subscription charge it relates to rather than below it.

The same change can produce two different numbers

This is the part that surprises people who assume a proration is arithmetic with one right answer.

Stripe offers two calculation modes for credit prorations, selected by the subscription's billing mode, and documents a scenario where they disagree. A 10 USD subscription is upgraded to 20 USD with prorations switched off, then downgraded back to 10 USD ten days later with prorations switched on.

Under classic billing mode, Stripe "creates a credit proration based on the current price, even though the customer never paid the 20 USD monthly rate", producing an invoice total of -3.34 USD. Under flexible billing mode, it "creates a credit proration based on the last price billed for the subscription item", and the credit and debit cancel out to an invoice total of 0 USD.

Same customer, same two actions, same dates. A refund in one mode and nothing at all in the other.

The modes also differ on how a coupon is weighted into a credit. Stripe walks through cancelling a 10 USD item from a 25 USD subscription carrying a 5 USD coupon: classic distributes the coupon evenly and calculates -0.5 x (10 USD price - 5 USD coupon) for -2.50 USD, while flexible uses the proportionally allocated discount, -0.5 x (10 USD price - 1.66 USD discount amount), for -4.17 USD.

The reason to know this is diagnostic. If a prorated credit does not match what you expected, the first question is not whether Stripe miscalculated. It is which billing mode the subscription is on, and what price was last actually billed on it.

What creates a proration, and what only looks like it should

Stripe draws the line at whether a change affects the billable amount for the current cycle.

Changes that do trigger prorations by default: adding or removing subscription items, changing an item's price, changing an item's quantity, adding a trial end to an active subscription, changing the billing cycle anchor, and setting a cancellation date inside the current period.

Changes that do not: payment method, collection method, automatic tax, metadata, billing thresholds, pausing collection, and cancelling at period end. Stripe explains the rule as a group: these "don't change the billing amount for the current period".

Discounts sit in that second group and are the common surprise. Stripe: "Updating subscription-level promotion codes, coupons, or discounts by themselves doesn't create proration invoice items." Adding a coupon mid-cycle does not credit the customer for the part of the month they paid full price on. The coupon applies from the next invoice.

There is a compound case worth holding onto, because it is the one that produces unexpected numbers. If a discount change is bundled into the same API call as a proration-triggering change, the proration is computed against the modified discount. Change a quantity and remove a coupon in one call and the proration reflects the post-removal price.

One more boundary: prorations "only apply to charges that occur ahead of the billing period", and Stripe states plainly that "Usage-based billing isn't subject to proration". Metered usage is billed for what was used, so there is nothing unused to credit back.

A proration is calculated immediately and billed later

Two timing facts do most of the work in explaining why prorations show up where they do.

The first: "The prorated amount is calculated as soon as the API updates the subscription." The number is fixed at the moment of the change, using the current period's start and end.

The second: it does not necessarily move money then. Stripe is explicit that "Negative prorations aren't automatically refunded and positive prorations aren't immediately billed, although you can do both manually." Under the default proration behaviour, proration items sit as pending invoice items and are "only invoiced immediately under certain conditions". Otherwise they wait for the next invoice.

That gap between calculation and billing is why an upgrade can produce no charge on the day it happens and a strange-looking total three weeks later. Anyone reconciling by date will look for the money on the change date and not find it.

A third fact is worth flagging because it produces credits that feel wrong. Stripe calculates prorations "assuming that any previous invoices for the subscription will eventually be paid", so a customer who changes plans while carrying an unpaid invoice "might receive a credit for unused time on the higher-priced plan, even if they haven't paid for that time yet". The credit is real, the payment behind it may never arrive.