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.

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.

1. 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.

1. 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.

1. 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.

1. 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.

1. 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