Adds billing schedules to enable prebilling on subscriptions
What’s new
You can now collect payment for future billing periods before they begin by specifying billing schedules when you create, update, or preview subscriptions. Billing schedules determine the future period to bill for and can apply to some or all of the items in the subscription.
The new billed_until property on subscription items allows you to see when the prebilled period ends for each item.
Impact
You can now prebill customers for future periods before they begin. Common use cases include:
| Use case | Description |
|---|---|
| Prepay multiple months at signup | Charge a monthly subscriber upfront for 3 months when they sign up, then resume normal monthly billing from that point. |
| Early renewal billing | When a renewal is 7 days away, generate and send the customer the renewal invoice now instead of waiting for the end of the billing cycle. |
| Annual payment on a monthly price | Let a customer pay for 12 months of a monthly plan in one upfront invoice, without changing the underlying price to an annual interval. |
| Early cancellation fee | Charge a customer for the remaining term of a committed contract when they cancel early by prebilling through the end of the commitment, then canceling the subscription. |
Learn more about configuring prebilling for subscriptions.
Changes
| Parameters | Change | Resources or endpoints |
|---|---|---|
| billing_schedules | Added | Invoice#create_preview. subscription_details Subscription Subscription#create + 1 more Subscription#update |
| billed_until | Added | SubscriptionItem |
Upgrade
- View your current API version in Workbench.
- If you use an SDK, upgrade to the corresponding SDK version for this API version.
- If you don’t use an SDK, update your API requests to include Stripe-Version: 2026-05-27. dahlia
- Upgrade the API version used for webhook endpoints .
- Test your integration against the new version.
- If you use Connect, test your Connect integration .
- In Workbench, perform the upgrade . You can roll back the version for 72 hours.
Learn more about Stripe API upgrades.
Related changes
- Adds discount eligibility options for add-on invoice items on Subscriptions and Preview Invoice APIs
- Adds amount paid off Stripe property to Invoice object
- Adds discount and discounts properties to pending subscription updates
- Adds metadata support to pending subscription updates
- Adds credited items information to invoice item proration details
- Adds customer parameter to test clock creation