Stripe subscriptions support billing schedules for prebilling future periods
Introduced 2026-05-27 · score 0.99
HOW TO USE IT
When prebilling subscription periods, use `billing_schedules` on create or update to set the end date and target items. Read each subscription item's `billed_until` to see when its prebilled period ends.
curl https://api.stripe.com/v1/subscriptions -u "<<YOUR_SECRET_KEY>>:" -d "customer={{CUSTOMER_ID}}" -d "items[0][price]={{PRICE_ID}}" -d "billing_mode[type]=flexible" -d "billing_schedules[0][bill_until][type]=duration" -d "billing_schedules[0][bill_until][duration][interval]=month" -d "billing_schedules[0][bill_until][duration][interval_count]=2"curl https://api.stripe.com/v1/subscriptions/{{SUBSCRIPTION_ID}} -u "<<YOUR_SECRET_KEY>>:" -d "billing_schedules[0][bill_until][type]=duration" -d "billing_schedules[0][bill_until][duration][interval]=month" -d "billing_schedules[0][bill_until][duration][interval_count]=2"WHY THIS HELPS
When implementing subscription billing that collects payment before a future period begins, create, update, or preview the subscription with a billing schedule and inspect each item's billed_until value.
REQUIREMENTS AND LIMITATIONS
- billing_schedules: Array of billing schedule objects for the subscription.
- billing_schedules[].applies_to[].type: Use `price` to target items by price; omit `applies_to` to prebill all applicable licensed-price items.
- billing_schedules[].applies_to[].price: Price ID of an item to prebill when `type=price`.
- billing_schedules[].bill_until.type (required): Select `duration` or `timestamp`; these alternatives are mutually exclusive.
- billing_schedules[].bill_until.duration.interval (required): Duration unit, such as `month`.
- billing_schedules[].bill_until.duration.interval_count (required): Number of duration units.
- billing_schedules[].bill_until.timestamp (required): Unix timestamp for the prebilling end date when `type=timestamp`.
- billing_schedules[].proration_behavior: Controls invoice timing: `always_invoice` generates the prebilling invoice immediately; `create_prorations` generates it at the next natural billing cycle.
- billing_mode[type] (required): Set to `flexible`; prebilling requires flexible billing mode.
- billed_until: Subscription item property showing when that item's prebilled period ends.
- Prerequisite: Prebilling requires flexible billing mode and API version `2026-05-27.dahlia` or later.
- Prerequisite: For an existing subscription, it must already use `billing_mode=flexible`.
- Billing schedules can apply to some or all items in a subscription.
- Docs conflict: The release note says billing schedules can apply to some or all subscription items. The prebilling guide narrows this: all-item prebilling covers applicable licensed-price items; usage-based prices are excluded. The guide also says prebilling cannot be used with subscription schedules or subscriptions backed by one.
FIRST-PARTY EVIDENCE
- https://docs.stripe.com/changelog/dahlia/2026-05-27/subscriptions-billing-schedules
- https://docs.stripe.com/billing/subscriptions/prebilling
- https://docs.stripe.com/api/subscriptions/create?api-version=2026-05-27.dahlia
Check the installed version and the source before using it. Entry JSON