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

TL;DR: TL;DR: # 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 # 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

TL;DR: # 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

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.

When to use

You hit exactly this: Stripe proration surprise: why the invoice amount was not what you expected in Stripe proration surprise.

When not to use

A different error, or the same symptom in a different tool. This page only covers the failure above.

Compatibility

Stripe proration surprise.

Stripe's proration documentation defines the three prorationbehavior values: createprorations defers to the next invoice, always_invoice bills immediately, none skips proration (docs.stripe.com/billing/subscriptions/prorations). Stripe documents that changing a subscription with an unpaid latest invoice can credit unused time that was never paid for, with no automatic guard, and recommends disabling prorations in that case.