Stripe proration surprise: why the invoice amount was not what you expected

# Stripe proration surprise: why the invoice amount was not what you expected

## The symptom

A plan change, seat change, or quantity change produced an invoice with a strange amount: a credit the customer did not earn, a charge that arrived immediately instead of next cycle, or no charge at all when one was due.

## Confirm the cause

Pull the invoice lines and look for `proration: true` line items. Then check what `proration_behavior` your update call sent. The three values:

- `create_prorations` (the default) - calculates the credit/charge difference and parks it as pending items on the *next* invoice. The customer sees it later, not now.
- `always_invoice` - same calculation, but generates and attempts payment on an invoice *immediately*.
- `none` - no proration at all. The new price simply starts next cycle.

Most surprises are the default: code that never set `proration_behavior` got `create_prorations` and the team expected immediate billing, or set `always_invoice` on a downgrade and charged the customer right away for a credit they should have received.

## The trap to check

If the subscription's latest invoice is unpaid and you change the plan with prorations enabled, Stripe can credit the customer for unused time on the higher-priced plan *even though they never paid for that time*. There is no automatic guard. When the latest invoice is unpaid, pass `proration_behavior: 'none'` or settle the invoice first.

Also check `payment_behavior` on upgrades: without `error_if_incomplete`, a declined card leaves the subscription upgraded and unpaid while your database agrees with the upgrade.

## The fix

1. Always pass `proration_behavior` explicitly. Never rely on the default.
2. Before any plan-change UI ships, call the upcoming-invoice preview so the customer sees the exact amount first.
3. On downgrades you usually want `create_prorations` (credit next invoice) or `none` (grandfather the period). On upgrades you usually want `always_invoice`.
4. Guard the unpaid-invoice case: if `latest_invoice.status != 'paid'`, use `none`.

## Verify the fix

In test mode with a test clock: create a subscription, advance mid-cycle, change the price with each of the three behaviors, and confirm the resulting invoices match the table (deferred vs immediate vs none). Then repeat with an unpaid latest invoice and confirm no phantom credit appears.