Stripe invoice preview supports subscription pauses
Introduced 2026-06-24 · score 0.97
HOW TO USE IT
When previewing a subscription pause, create a preview invoice with `subscription_details.pause`, `invoicing_behavior=invoice`, and `bill_for` settings that produce billable unused time or metered usage. Use the returned preview invoice and expanded projected subscription state; the preview does not modify the subscription.
curl https://api.stripe.com/v1/invoices/create_preview \
-u "<<YOUR_SECRET_KEY>>:" \
-d subscription=<SUBSCRIPTION_ID> \
-d "subscription_details[pause][invoicing_behavior]=invoice" \
-d "subscription_details[pause][bill_for][unused_time_from][type]=now" \
-d "subscription_details[pause][bill_for][outstanding_usage_through][type]=now" \
-d "expand[]=parent.subscription_details.subscription"WHY THIS HELPS
When implementing subscription pausing, preview the billing impact and projected subscription state before changing the subscription.
REQUIREMENTS AND LIMITATIONS
- Availability: Preview API version 2026-06-24.preview
- subscription (required): Subscription identifier for the upcoming invoice preview.
- subscription_details.pause.invoicing_behavior (required): Set to `invoice` to receive a preview invoice; `pending_invoice_item` returns 404.
- subscription_details.pause.bill_for.unused_time_from.type (required): `now` credits unused licensed time from pause time; `item_current_period_start` credits from each item's period start; `none` does not credit unused time.
- subscription_details.pause.bill_for.outstanding_usage_through.type (required): `now` bills metered usage from current period start through pause time; `none` does not bill current-period metered usage.
- expand[]: Set to `parent.subscription_details.subscription` to see the projected subscription state after pausing; these changes do not persist.
- Prerequisite: For a restricted API key, grant `invoice_read` to preview invoices.
- Prerequisite: A valid subscription/customer must be provided; preview invoice creation requires valid customer information.
- `invoicing_behavior` must be `invoice` to receive a preview invoice; `pending_invoice_item` returns a 404 error.
- `bill_for` must produce billable amounts for unused licensed time or outstanding metered usage; if pausing would not create debits or credits, the endpoint returns a 404 error.
FIRST-PARTY EVIDENCE
- https://docs.stripe.com/changelog/dahlia/2026-06-24/preview-invoices-before-pausing-subscription
- https://docs.stripe.com/billing/subscriptions/pause#preview-the-invoice-before-pausing
- https://docs.stripe.com/api/invoices/create_preview?api-version=2026-06-24.preview
- https://docs.stripe.com/billing/subscriptions/pause#how-pausing-affects-billing
- https://docs.stripe.com/billing/subscriptions/pause#before-you-begin
Check the installed version and the source before using it. Entry JSON