Adds billing mode to control how prorations and invoices for subscriptions are calculated and orchestratedPublic preview
What’s new
The new billing_ parameter lets you enable more flexible behavior when you create Subscriptions, Invoice Previews, Checkout Sessions, or Subscription Schedules.
| billing_mode=classic | billing_mode=flexible |
|---|---|
| Credit proration amounts are calculated based on the value of the subscription item’s current price, tax, quantity, and the last discounts used. This could lead to unexpected prorations when a customer’s tax rates change mid-cycle, debit prorations are disabled, or complex amount-off coupons are used. | Credit prorations are calculated based on the original amount previously debited to a customer. This improves proration calculations to take into account taxes, coupons, and billing cycle considerations. For example, credit prorations will now accurately credit back taxes based on the original debit (if tax rate changed mid-cycle) and credit prorations will not be issued if there was no debit. |
subscription. is unchanged when a subscription goes back to trialing state. | subscription. is updated to reflect the most recent trial start date. |
The billing_cycle_anchor is sometimes reset during other operations:
| billing_cycle_anchor isn’t reset during other operations:
|
Configuring billing_ to flexible has limitations. Learn more about the limitations and how billing mode enables flexible behavior for subscriptions.
Impact
You can set billing_ to be flexible on the following API methods that create a subscription:
- Create a subscription
- Create an invoice preview
- Create a checkout session
- Create a subscription schedule