Skip to content
Tutorials Center
My learning

Topics

Lesson 19 of 38 ยท Subscriptions and Billing

Invoices, Proration and Plan Changes

Learn how Stripe invoices work, their lifecycle from draft to paid, how proration prices mid-cycle upgrades and downgrades, and how to preview changes with a runnable proration calculator.

Every subscription charge is an invoice (in_...). Stripe generates one at the start of each billing period, lists what is being billed on line items, applies discounts, tax and credits, and then tries to collect the total with the customer's payment method. Understanding invoices turns a lot of confusing situations (a surprise amount, a credit that appeared, a charge for a change made last week) into simple arithmetic. This lesson covers the invoice lifecycle and the most important calculation, proration.

The invoice lifecycle

An invoice moves through statuses:

Status Meaning
draft Being built; can still change. Subscription invoices stay draft for about an hour so webhooks can adjust them
open Finalized and waiting for payment
paid Collected
void Cancelled; never collectable, kept for the record
uncollectible You gave up collecting; marked as bad debt
flowchart LR
  D["draft"] -->|"finalize<br/>(about 1 hour)"| O["open"]
  O -->|"payment succeeds"| P["paid"]
  O -->|"cancel it"| V["void"]
  O -->|"give up"| U["uncollectible"]
  U -->|"customer pays anyway"| P

Events along the way: invoice.created, invoice.finalized, invoice.paid, invoice.payment_failed.

Two behaviours are worth knowing. The first invoice of a subscription is created and paid immediately; later ones finalize roughly an hour after creation, which is your window to add one-off items or react to invoice.created. And Stripe emails receipts or invoices according to your settings, and hosts a invoice page and PDF for each (hosted_invoice_url, invoice_pdf).

Invoice line items

A typical renewal invoice has:

  1. the subscription line (price x quantity for the coming period),
  2. optional proration lines (credits for unused time, charges for new time),
  3. discounts (coupons, promotion codes),
  4. tax lines,
  5. an applied customer balance (credit from earlier cancellations, which reduces what is charged).

You can add invoice items (stripe.invoiceItems.create) for one-off extras such as a setup fee, and they join the customer's next invoice.

What proration is

Suppose a customer pays $30 per month, and on day 10 of a 30-day cycle upgrades to a $60 plan. They already paid for 30 days of the cheap plan, but they will use only 10 of them; and they need the expensive plan for the remaining 20. Proration adjusts for exactly that:

  • a credit for the unused part of the old plan: 20/30 of $30 = $20.00,
  • a charge for the remaining part of the new plan: 20/30 of $60 = $40.00,
  • net to pay now: $20.00.

Stripe calculates proration by seconds within the current period, not by whole days, and shows each as its own invoice line. The default behaviour when you change a subscription is to create prorations and add them to the next invoice (proration_behavior: "create_prorations"). Other values:

proration_behavior Effect
create_prorations Compute the lines; collect them on the next invoice (default)
always_invoice Compute and invoice and charge now
none No proration; the new price simply applies from the next period
JavaScript
// Real Stripe usage (read-only).
const sub = await stripe.subscriptions.retrieve("sub_123");
await stripe.subscriptions.update("sub_123", {
  items: [{ id: sub.items.data[0].id, price: "price_pro_monthly" }],
  proration_behavior: "always_invoice",
});

Upgrade on day 10 of 30

Credit Unused old plan
Charge Rest of new plan
Net The difference
1 / 2

A proration calculator

Here is the logic in code. It is a stand-in calculation of the idea (Stripe works to the second); the integer rounding rule shown is one reasonable choice.

Node.js Compute a mid-cycle upgrade

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

A negative net after a downgrade becomes a credit on the customer's balance, applied automatically to future invoices, not cash back to the card. That surprises people: explain it in your UI.

Previewing before committing

Never surprise customers with a number. Stripe offers an upcoming invoice preview (the Create Preview Invoice API) that returns what the invoice would look like after a proposed change, including prorations, tax and discounts. Show that total on the "Confirm upgrade" screen. Pass the same proration_date timestamp when you commit the change, so the calculation matches the preview even if a few seconds pass.

Node.js Preview then confirm (stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Quantity changes and billing anchors

Changing a seat count (quantity) prorates the same way as changing a price. Another important setting is the billing cycle anchor: the day of the month renewals happen. By default it is the day the subscription started. You can align all customers to the 1st of the month, with a prorated first partial period, using billing_cycle_anchor, which makes accounting easier at the price of confusing first invoices.

Credit notes

Once an invoice is finalized you cannot edit it. To reduce it, issue a credit note (cn_...), which can refund the card, reduce the customer balance, or mark it as out-of-band. Refunding a charge directly does not adjust the invoice's accounting, whereas a credit note keeps your tax and revenue reports accurate.

Next: what happens when renewal payments fail, and how to give customers control: Billing Portal, Retries and Dunning.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. A $30 plan is upgraded to $60 exactly halfway through the period. What is the net proration?

    Credit for half of $30 is -$15; charge for half of $60 is $30; net is $15.
  2. 2. Which proration_behavior charges the customer immediately for the change?

    always_invoice creates the invoice and collects it now; create_prorations waits for the next invoice.
  3. 3. After a downgrade creates a negative net, where does the money go?

    Credits from proration reduce the next invoice; they are not automatic refunds.
  4. 4. How do you reduce an invoice that is already finalized?

    Finalized invoices are immutable; credit notes record the adjustment properly.

Summary

  • Every subscription renewal is an invoice: draft, open, paid, void or uncollectible.
  • Proration credits unused time on the old plan and charges the remaining time on the new one, computed by seconds.
  • proration_behavior chooses when the difference is collected.
  • Preview upcoming invoices and reuse the same proration timestamp when applying.
  • Use credit notes to adjust finalized invoices.

Next: Billing Portal, Retries and Dunning