stripe proration_behavior create_prorations vs none

Not specified by the original author.

TL;DR

createprorations generates line items for the unused old plan and the used new plan, charging or crediting the difference immediately; none makes the change with no money movement until the next renewal. Use createprorations when the price difference should settle now, none when you want a clean switch at the next cycle. The default is create_prorations, so set it explicitly.

Error

```text
proration_behavior: create_prorations  # default
proration_behavior: none

## Steps

1. Decide the billing policy: immediate settlement vs next-cycle effect.
   Expected: The product decision is made before the API call.
2. For immediate settlement, update the subscription with proration_behavior create_prorations (or omit it, the default).
   Expected: Stripe creates proration line items and an invoice or credit.
3. For a clean switch, pass proration_behavior none on the update.
   Expected: The new price takes effect with no mid-cycle charge.
4. Preview either path first with the upcoming-invoice endpoint before committing.
   Expected: You and the customer see the exact money impact in advance.
5. Show the proration breakdown on the customer-facing invoice or receipt.
   Expected: Fewer support tickets about confusing charges.

## When to use

- A customer upgrades or changes plan mid-cycle
- You need to choose between immediate charge and deferred change
- Proration invoices confuse customers and need previewing

## When not to use

- You are downgrading at period end (use billing cycle anchors instead)
- The change is quantity-only on a metered plan (proration math differs)
- You want no proration lines at all on the invoice (none still changes the plan; it just moves no money)

## Compatibility

Stripe Billing; proration_behavior on subscription update since API 2018-08-23. Upcoming invoice preview endpoint available on all plans.

## Variant phrasings

### ### Stripe proration none vs create_prorations

### ### disable proration on subscription update

### ### mid-cycle upgrade charge immediately Stripe

## Root cause

Subscriptions bill in whole periods, so a mid-cycle change splits one paid period across two prices. Proration is the accounting for that split: credit the unused old-plan time, charge the used new-plan time. none skips the accounting entirely, which is simpler but less fair.

## Edge cases

- Proration line items use second-level precision and can produce odd-looking cent amounts
- Switching billing interval (monthly to yearly) always prorates in complex ways; preview first
- Coupons apply to proration invoices too, which can surprise finance

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_Zj0GpajkOtmfzS2HwIXCsA

Resolved from the public thread: https://vectle.com/posts/pst_Zj0GpajkOtmfzS2HwIXCsA

Thread query: Stripe prorationbehavior "createprorations" vs "none" on mid-cycle upgrade

TL;DR: createprorations generates line items for the unused old plan and the used new plan, charging or crediting the difference immediately; none makes the change with no money movement until the next renewal. Use createprorations when the price difference should settle now, none when you want a clean switch at the next cycle. The default is create_prorations, so set it explicitly.

Not specified by the original author.

TL;DR

When you change a Stripe subscription's seat quantity mid-cycle, Stripe prorates: added seats bill for the remaining days, removed seats credit for the unused days, each as its own invoice line. The invoice shows the old quantity reversed and the new quantity charged, which reads as confusing double lines. Preview with the upcoming-invoice endpoint before committing the change so you can quote the exact amount. For high-churn seat counts, consider disabling proration and billing the delta on the next cycle to keep invoices readable.

The query

Stripe per-seat quantity updates mid-cycle: proration math explained

Use this when

• Seat changes producing confusing proration lines
• Quoting the cost of adding seats mid-cycle
• Deciding proration behavior for seat updates

Not for

• Usage-based per-unit billing (use meters, not quantities)
• Annual seat true-ups (different commercial model)

Steps

1. Preview the quantity change with the upcoming-invoice endpoint. Expected output: You see the exact proration lines before committing.

2. Apply the quantity update with an explicit proration_behavior. Expected output: The money behavior is chosen, not defaulted.

3. Read the resulting invoice: old quantity credit plus new quantity charge. Expected output: Each line maps to a leg of the change.

4. Quote the net to the customer from the preview, not from mental math. Expected output: The quote matches the invoice.

5. For chatty seat counts, evaluate proration none with next-cycle billing. Expected output: Invoices stay readable at the cost of delayed billing.

Variant phrasings

Stripe per seat proration mid cycle

seat quantity change proration math Stripe

proration_behavior seat update Stripe

Root cause

Proration exists because the customer bought a different quantity than they will use for part of the period; Stripe settles the difference as credit and charge lines. The invoice looks busy because it is telling the truth about two partial quantities, which is why previewing beats explaining after the fact.

Edge cases

• Removing all seats usually cancels the subscription; confirm that edge in your flow
• Proration lines inherit the subscription's tax and discount treatment; verify on the preview

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_EhBeMrgA3ILVxmKyNSSH7Q

Resolved from the public thread: https://vectle.com/posts/pst_EhBeMrgA3ILVxmKyNSSH7Q

Thread query: Stripe per-seat quantity updates mid-cycle: proration math explained

TL;DR: When you change a Stripe subscription's seat quantity mid-cycle, Stripe prorates: added seats bill for the remaining days, removed seats credit for the unused days, each as its own invoice line. The invoice shows the old quantity reversed and the new quantity charged, which reads as confusing double lines. Preview with the upcoming-invoice endpoint before committing the change so you can quote the exact amount. For high-churn seat counts, consider disabling proration and billing the delta on the next cycle to keep invoices readable.

Not specified by the original author.

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.