Bill customers in advance

Use prebilling to collect payment now for multiple future service periods.

With prebilling, you can bill customers in advance for multiple service periods. You can enable prebilling when you create a subscription or add it to an existing one.

Flexible billing mode and API version required

Prebilling requires subscriptions with flexible billing mode enabled and API version 2026-05-27.dahlia or later. If you haven’t enabled flexible billing mode yet, see Flexible billing mode to get started.

Use cases

With prebilling, you can collect payment upfront for future service periods. Common use cases include:

Limitations

Prebilling has the following limitations:

• Prebilling doesn’t change when a service period starts or automatically generate an invoice a set number of days before that date. To collect payment a set number of days before the next service period, trigger a subscription update on that date and set bill _ until to the end of the period you want to prebill.
• You can’t use prebilling with subscription schedules or subscriptions backed by a subscription schedule. Expired billing _ schedules entries remain on a subscription. To create a subscription schedule from that subscription later, update the subscription with an empty billing _ schedules value to remove them.
• You can only use coupons with percent_off and a duration of once or forever with prebilling.
• You can’t enable prebilling if all the subscription items have usage-based prices. Prebilling doesn’t apply to any usage-based prices in a subscription. You can’t set applies_to[price] if the price has usage_type=metered .
• If a subscription is scheduled for cancellation and you try to set the prebilling end date past the scheduled cancellation date, the end date is automatically set to the scheduled cancellation date.
• You can’t set payment _ behavior to pending _ if _ incomplete when you update a subscription with an active billing schedule. Use another payment behavior .

How prebilling works

Prebilling uses billing_schedules on a subscription to define which items to bill upfront and for how long. When you configure billing_schedules, Stripe generates an advance invoice that covers all specified future service periods at the time the subscription is created or updated, rather than waiting for each billing cycle to occur.

Prebilling applies at the item level: you can prebill specific items by passing the applies_to parameter with the price IDs to target, or omit applies_to entirely to prebill all applicable licensed-price items on the subscription. Usage-based prices are never included in prebilling, regardless of the applies_to configuration.

The bill_until parameter controls the end date of the prebilled period. You can express this as a duration (for example, 2 months from the current date) or as a timestamp (a specific Unix timestamp).

Create a subscription with prebilling

To configure prebilling when creating a subscription, use billing_schedules to specify which items to prebill and how long to prebill for.

• Use applies _ to to specify which items to prebill by price ID. Omit this parameter to prebill all applicable items.
• Use bill _ until to set the end date for prebilling as a duration or timestamp.
• Use proration _ behavior to control when the prebilling invoice is generated.

When you set the end date for prebilling:

• Set the end date at least one full billing period from the start. For example, for a monthly subscription, the end date must be at least one month from the start of the billing period.
• If the end date isn’t aligned with the end of a billing period, the part of the period before the end date gets prebilled. The remainder is billed separately according to the subscription configuration.
• The total prebilled cycles across all items can’t exceed 50. For example, with two items you could prebill each for up to 25 months.
• Don’t set the end date more than 5 years in the future.

To create a subscription with prebilling in the Dashboard:

1. Go to the Subscriptions page .
2. Click + Create subscription .
3. In the Subscription settings section, enable Bill upfront .
4. Select the end date for prebilling. All items in the subscription are prebilled until the date you select.
5. In the Advanced settings section, set Billing mode to Flexible .
6. Click Create subscription .

To update an existing subscription:

Note

The subscription must already be in billing_mode=flexible to enable prebilling. See Limitations for more details.

1. Go to the Subscriptions page .
2. Click the subscription to update, then select Actions > Update subscription .
3. In the Subscription settings section, enable Bill upfront .
4. Select the end date for prebilling. All items in the subscription are prebilled until the date you select.
5. Click Update subscription .

Update an existing subscription with prebilling

To add prebilling to an existing subscription, update the subscription with the billing_schedules parameter. The subscription must already be in billing_mode=flexible.

Command Line

Select a language

cURL

Stripe CLI

Ruby

Python

PHP

Java

Node.js

Go

.NET

No results

Bill an upcoming renewal early

Prebilling doesn’t automatically generate an invoice a set number of days before a service period starts. To collect an upcoming renewal early, update the subscription on the date you want to bill. Set billing_schedules.bill_until to the end of the upcoming service period and set proration_behavior to always_invoice to generate and finalize the invoice immediately.

For example, to bill a monthly renewal 7 days before the current period ends, schedule this update for that date with the timestamp set to the end of the upcoming period:

Command Line

Select a language

cURL

Stripe CLI

Ruby

Python

PHP

Java

Node.js

Go

.NET

No results

Early cancellation fees

Use prebilling to charge customers for the remaining term of a committed contract when they cancel early. This is common for fixed-term subscriptions that bill on a recurring (for example, monthly) cadence.

For example, a customer signs up on January 1 for a 1-year monthly plan at 10 USD/month. They cancel on September 10. To collect the remaining commitment, prebill the subscription through December on the final invoice, then cancel the subscription with no proration.

1. Update the subscription to set billing _ schedules. bill _ until to the end of the committed term (December 31) and set proration _ behavior to always _ invoice . This generates and finalizes the invoice for the remaining term immediately.
2. After the update succeeds, cancel the subscription , setting prorate to false .

The customer’s final invoice includes charges for October, November, and December, which covers the remainder of their commitment as an early cancellation fee. Canceling after the update doesn’t add another proration because prorate was set to false.

This pattern also works for longer committed contracts (for example, a 2-year contract where the customer cancels at month 18) and for early renewal scenarios where customers upgrade mid-term and prepay the remaining period at the new price.

Additional considerations

Invoice generation timing

The prebilling invoice is generated when you create or update a subscription with billing_schedules configured. The exact timing depends on your proration_behavior setting:

• always _ invoice : Generates and finalizes the prebilling invoice immediately when the subscription is created or updated.
• create _ prorations : Generates the prebilling invoice at the next natural billing cycle date.

Use always_invoice if you want the customer to receive the advance invoice right away. Use create_prorations if you want the invoice to appear alongside the customer’s regular invoice at their next billing date.

Webhooks and events

Prebilling generates invoices outside the normal billing cycle. Make sure your integration handles the relevant events. For example, you might want to send the customer a receipt when the prebilling invoice is paid, or handle payment failure with a retry flow.

Preview the prebilling invoice

You can preview a customer’s invoice before you create or update a subscription to use prebilling. Use the API to create a preview invoice and include billing_schedules in the subscription_details parameter. This shows you the invoice generated for prebilling.

Interaction with coupons

Only coupons with percent_off and a duration of once or forever are compatible with prebilling. amount_off coupons and coupons with duration=repeating return an error when used with a subscription that has billing_schedules configured.

See also

• Flexible billing mode
• Prorations
• Preview invoices
• Subscription billing cycle