Adds billing mode for more flexible subscriptions behavior

Proration

Accurate credit proration calculation. Flexible billing mode consistently uses the original debited amount, accurately accounting for historical taxes, discounts, and billing cycles.

Proportional discount application for prorations. We apply discounts proportionally to each subscription item during proration calculations instead of distributing them evenly. This results in more prorations, especially when invoicing on a per-item basis or canceling items with unevenly distributed discounts.

Metered pricing

Suppresses zero-amount line items when adding metered items. Flexible billing mode doesn’t create zero-amount line items when you add metered items to a subscription. If the invoice is empty as a result, we don’t generate one.

Bills metered usage based on the price at the time of reporting. Flexible billing mode bills for usage based on the price at the time you report it. If a metered item’s price changes during a period, only usage reported after the price change is billed at the new price.

Bills for unbilled usage when removing metered items. Flexible billing mode generates an invoice item for unbilled usage when you remove a metered subscription item. This applies to removals using the API or during schedule phase transitions.

Consolidates invoices for phase transitions with metered items. Flexible billing mode consistently generates a single invoice when a subscription cycles, eliminating separate invoices for removed metered items.

Trials

Updates the trial start date for subsequent trials. When you add a second trial to a trialing subscription, flexible billing mode uses the most recent trial’s start date.

Preserves the original trial end date when the cancellation date changes. Flexible billing mode preserves the trial_end if you modify the cancel_at date to occur before the trial ends.

Standardizes the trial period line item description. With flexible billing mode, both metered and licensed items use a consistent description format—“Free trial for {quantity} x {product name}”—for a more uniform presentation of trial information.

Generates line items for changes made during a trial. In flexible billing mode, items that haven’t changed aren’t re-billed. This ensures that customers are only billed for the adjustments they make during their trial.