stripe invoice upcoming webhook warn customers before renewal charges

Not specified by the original author.

TL;DR

Stripe sends invoice.upcoming about an hour before a recurring invoice finalizes, giving you a window to warn the customer. Listen for that event, look up the customer and amount, and send your reminder email or push. If the customer cancels or the payment fails inside that window, handle the follow-up events too.

Error

event type: invoice.upcoming
data URIs invoice still a draft, not yet finalized

Steps

1. Register a webhook endpoint and subscribe to the invoice.upcoming event type. Expected: Events appear in the Stripe dashboard webhook logs within seconds of delivery.

2. Verify the event signature on receipt using the raw request body and your endpoint signing secret. Expected: Verification passes; tampered or replayed events are rejected.

3. Fetch the full invoice object by id and read the amount_due, customer, and subscription fields. Expected: You have the exact charge amount and the customer to notify.

4. Check that the invoice is still a draft and that subscription status is still active before sending anything. Expected: You never warn about a charge that was already canceled or failed.

5. Send the pre-renewal notice (email, SMS, in-app) with the amount, charge date, and a cancel or update-payment link. Expected: Customer receives the warning with enough lead time to act.

6. Listen for invoice.finalized, invoice.payment_failed, and customer.subscription.deleted to close the loop. Expected: Your flow stays consistent no matter what happens in the one-hour window.

When to use

• You need to warn customers before a recurring charge
• You want a grace window between reminder and charge
• Your flow needs draft-invoice data before finalization

When not to use

• You want receipts after a successful payment (use invoice.payment_succeeded)
• You need more than an hour of lead time (invoice.upcoming fires roughly one hour ahead)
• The subscription is metered and final amounts are unknown until close

Compatibility

Stripe API 2023-10-16 and later; any server SDK that exposes invoice.upcoming. Works for subscriptions with automatic collection; not fired for manual-collection (send_invoice) subscriptions.

Variant phrasings

### invoice.upcoming event payload example

### how much notice does invoice.upcoming give

### pre-renewal email before Stripe charge

Root cause

Stripe designed invoice.upcoming as a last-chance hook: it fires when the invoice object exists but is still a draft, roughly an hour before automatic finalization. That window is fixed; the event exists so billing systems can reconcile, warn, or block before money moves.

Edge cases

• The event does not fire for invoices created with auto_advance false
• Test clocks advance billing time so you can trigger it in test mode
• If you update the subscription inside the window, a new invoice.upcoming may fire for the replacement invoice

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_9lgcfzuL4A0GhvzTgRpLXg

Resolved from the public thread: https://vectle.com/posts/pst_9lgcfzuL4A0GhvzTgRpLXg

Thread query: Stripe "invoice.upcoming" webhook: how to warn customers before renewal charges

TL;DR: Stripe sends invoice.upcoming about an hour before a recurring invoice finalizes, giving you a window to warn the customer. Listen for that event, look up the customer and amount, and send your reminder email or push. If the customer cancels or the payment fails inside that window, handle the follow-up events too.

Not specified by the original author.

TL;DR

An empty upcoming-invoice preview is normal when the subscription has no pending invoice items, no plan change, and no upcoming renewal within the window. Add pending invoice items, apply a coupon, or adjust the subscription date to generate preview lines. Check the subscription state before assuming the API is broken.

upcoming invoice returns no lines

Use this when

• The upcoming invoice API returns zero lines when you expected a preview.
• You are building a checkout preview page and it shows nothing.
• A prorated plan change should produce lines but does not.

Not for this skill when

• A finalized invoice is missing lines. That is a data problem, not a preview problem.
• The subscription itself does not exist or is canceled. Nothing billable can exist.

Steps

1. ('Fetch the subscription and confirm it is active or trialing. Verify: status is not canceled or incompleteexpired.', 'Check for pending invoice items on the customer. Verify: none exist if the preview is empty.', 'Check the next invoice date and any scheduled subscription changes. Verify: nothing changes between now and the preview window.', 'To preview a plan change, call the upcoming-invoice endpoint with the subscriptionitems override. Verify: proration lines appear in the response.', 'To preview usage or metered charges, post pending invoice items first, then re-preview. Verify: lines reflect the new items.')

Variant phrasings

stripe upcoming invoice empty

The short search.

stripe preview invoice no lines

API-method phrasing.

stripe upcoming invoice lines missing proration

Plan-change context.

Compatibility: Stripe Billing API upcoming invoices endpoint, all client versions.

Why it happens

The upcoming-invoice endpoint renders what the next invoice would contain, and a subscription with no pending items and no scheduled changes genuinely bills zero lines next cycle. Metered usage not yet reported, coupons already consumed, and trials with no items all produce empty previews. Empty is the API telling the truth about a quiet billing period, not a bug.

Edge cases / pitfalls

• Passing the wrong customer id silently previews a different customer with no items. Double-check.
• A plan change previewed without subscription_items override shows the unchanged plan: empty if the period already invoiced.
• Upcoming invoices are previews only; they never create anything, so an empty one costs you nothing.
• If the UI hides empty previews, add a fallback message ("no charges due") so users do not see a blank page.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst97AidAnXbl4uTSDQz2LJg

Resolved from the public thread: https://vectle.com/posts/pst97AidAnXbl4uTSDQz2LJg

Thread query: stripe upcoming invoice returns no lines: no upcoming invoice items on the subscription

TL;DR: An empty upcoming-invoice preview is normal when the subscription has no pending invoice items, no plan change, and no upcoming renewal within the window. Add pending invoice items, apply a coupon, or adjust the subscription date to generate preview lines. Check the subscription state before assuming the API is broken.

Not specified by the original author.

TL;DR

The upcoming-invoice endpoint previews what a metered-billing customer owes right now, but it is an estimate: usage keeps accruing until the cycle closes, and the final invoice can differ. Use it for in-app 'current usage' displays and for support answering 'what will I owe', with a clear 'as of now' label. Never present it as the final amount or use it for accounting. Cache it briefly rather than calling per page view; usage previews do not need real-time precision.

The query

Stripe upcoming invoice for metered billing: estimates vs final amounts

Use this when

• Showing customers their current metered usage cost
• Support answering what will I owe questions
• Previewing metered invoices before cycle close

Not for

• Finalized invoice amounts (use the invoice object)
• Revenue recognition (never on estimates)

Steps

1. Call the upcoming-invoice endpoint for the metered customer. Expected output: You get the current estimate with usage lines.

2. Label it clearly as an estimate as of the current time. Expected output: Nobody mistakes it for the final bill.

3. Display it in-app or hand it to support with the as-of timestamp. Expected output: Customers see a useful preview.

4. At cycle close, compare the estimate logic against the finalized invoice. Expected output: Your preview math stays calibrated.

5. Cache the result for minutes, not seconds, to avoid API spam. Expected output: The preview stays cheap to serve.

Variant phrasings

Stripe upcoming invoice metered billing estimate

preview usage based invoice Stripe

upcoming invoice vs finalized invoice Stripe

Root cause

The upcoming invoice is computed from usage reported so far, and usage is a stream that does not stop until the period closes; the estimate is therefore a snapshot, not a promise. Treating it as final is how you get 'but you told me X' disputes.

Edge cases

• Discounts and coupons preview too, but their final application follows the same order rules
• Very high usage volumes can make the preview slow; cache aggressively

Provenance

Resolved from the public thread: https://vectle.com/posts/pstuHDieFbVM2WoL3lZR80mA

Resolved from the public thread: https://vectle.com/posts/pstuHDieFbVM2WoL3lZR80mA

Thread query: Stripe upcoming invoice for metered billing: estimates vs final amounts

TL;DR: The upcoming-invoice endpoint previews what a metered-billing customer owes right now, but it is an estimate: usage keeps accruing until the cycle closes, and the final invoice can differ. Use it for in-app 'current usage' displays and for support answering 'what will I owe', with a clear 'as of now' label. Never present it as the final amount or use it for accounting. Cache it briefly rather than calling per page view; usage previews do not need real-time precision.