Preview the amount before a plan change

How to do it

Upgrade at once and charge the prorated difference. Downgrade at the end of the period, so the customer keeps what they paid for. Ask the provider for a preview invoice, and pass the same proration time to the change itself, so the charge matches the preview. Quantity changes, such as more seats, follow the same rule. Store the confirmed amounts as Freeze what the customer agreed to on the order says.

Examples

JavaScript example

const prorationDate = Math.floor(Date.now() / 1000)
const items = [{ id: subscriptionItemId, price: 'price_team_monthly' }]
const preview = await stripe.invoices.createPreview({
  subscription: subscriptionId,
  subscription_details: { items, proration_date: prorationDate },
})
showAmountDueNow(preview.amount_due, preview.currency)
// After the customer confirms:
await stripe.subscriptions.update(subscriptionId, { items, proration_date: prorationDate })

Python example

proration_date = int(time.time())
items = [{"id": subscription_item_id, "price": "price_team_monthly"}]
preview = stripe.Invoice.create_preview(
    subscription=subscription_id,
    subscription_details={"items": items, "proration_date": proration_date},
)
show_amount_due_now(preview.amount_due, preview.currency)
# After the customer confirms:
stripe.Subscription.modify(subscription_id, items=items, proration_date=proration_date)

How to check

Upgrade a test subscription halfway through a month. The charged amount equals the previewed amount to the minor unit.

Sources

• Stripe prorations, preview a proration

Related rules

• PRC-15 Count seats from active members and check them at invite in Pricing, plans and entitlements
• PAY-12 Freeze what the customer agreed to on the order in Payments and billing