Stripe invoice.upcoming webhook: how to 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

invoice.created fires when the draft exists (useful for pre-finalize logic like invoice.upcoming warnings or custom validation); invoice.finalized fires when the invoice becomes real and billable (the trigger for fulfillment, revenue recognition, and dunning). Most post-billing automation belongs on invoice.finalized; use invoice.created only when you need the draft window. Listening to both without distinguishing them double-triggers flows.

Steps

1. List what each automation needs: draft-time intervention vs post-finalize action. Expected: Each listener gets a justified event.

2. Put pre-finalize logic (warnings, validation, edits) on invoice.created. Expected: Draft-window work runs before the invoice is real.

3. Put fulfillment, accounting entries, and dunning on invoice.finalized. Expected: Real-invoice work runs exactly once, on a real invoice.

4. Guard handlers with the invoice status so a misrouted event cannot double-fire. Expected: Defense in depth against duplicate processing.

5. Document the event map for your team so new automations pick the right hook. Expected: Future work inherits the correct pattern.

When to use

• You wire new invoice automation
• Handlers fire twice or at the wrong time
• You need draft-window vs finalized semantics

When not to use

• You handle payment outcomes (use invoice.payment_succeeded or failed)
• You need subscription lifecycle events (different webhook family)
• You only care about disputes (different family)

Compatibility

Stripe webhooks; invoice.created and invoice.finalized event types. All API versions with Billing.

Variant phrasings

### Stripe invoice.created vs finalized

### which invoice webhook to use Stripe

### invoice finalized webhook fulfillment

Root cause

The two events bracket the draft-to-real transition: created announces intent (the invoice might still change or never finalize), finalized announces commitment (number assigned, totals locked). Automation that acts on intent as if it were commitment fulfills orders for invoices that never bill.

Edge cases

• Manually finalized invoices fire finalized whenever you call it, which can be much later than created
• Voided drafts never fire finalized; handle the void path in your state machine
• Test clocks let you rehearse the full created-to-finalized sequence

Provenance

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

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

Thread query: Stripe invoice.created vs invoice.finalized: which webhook to listen for

TL;DR: invoice.created fires when the draft exists (useful for pre-finalize logic like invoice.upcoming warnings or custom validation); invoice.finalized fires when the invoice becomes real and billable (the trigger for fulfillment, revenue recognition, and dunning). Most post-billing automation belongs on invoice.finalized; use invoice.created only when you need the draft window. Listening to both without distinguishing them double-triggers flows.

Not specified by the original author.

TL;DR

Fix this in Stripe and the renewal brief by acting on the exact problem first: change the brief builder to read payment status from the invoice paid event in Stripe rather than the earlier subscription updated event, hold the brief status as pending until that paid event arrives, and regenerate the affected briefs once payment is confirmed. Do not rerun the whole workflow unchanged, because the same inputs produce the same failure. Prove the fix on one account first, then rerun the full scope and reconcile the results.

Stripe subscription updated webhook fires before renewal payment confirmed brief uses unpaid status

Use this when

• The operation in Stripe and the renewal brief fails with this exact problem: Stripe subscription updated webhook fires before renewal payment confirmed brief uses unpaid status.
• The same failure repeats on retry with unchanged inputs.
• A renewal, reminder, quote or playbook step is blocked until this is resolved.

Not for this skill when

• The notice is a platform outage from the vendor. Resolve that first, then return here if this problem remains.
• The operation completes and you only disagree with a commercial decision such as price or terms. That is a negotiation, not this failure.

Steps

1. Reproduce the failure on one named account in Stripe and the renewal brief and record the full problem text plus the account, contract or quote involved. Verify: the failure is reproduced on demand on a named scope, not only seen in a log.
2. Apply the specific fix for this problem: change the brief builder to read payment status from the invoice paid event in Stripe rather than the earlier subscription updated event, hold the brief status as pending until that paid event arrives, and regenerate the affected briefs once payment is confirmed. Verify: the single failing account now behaves as the fix predicts, or the corrected value is visible on the record.
3. Check neighbouring accounts, contracts or quotes that share the same automation, template or sync, because this class of failure rarely affects only one account. Verify: the neighbouring items are listed and each is marked affected or clear.
4. Rerun the original operation in Stripe and the renewal brief on the previously failing scope, watching for the same problem rather than assuming success from a quiet log. Verify: the operation completes and the original problem does not appear.
5. Compare the result against the source of truth, the signed contract, the billing record or the CRM opportunity, so a silent partial success is caught. Verify: values match the source or every difference is named and explained.
6. Record the fix, the triggering input and the verification result on the account so the next occurrence is recognised immediately. Verify: the record names the problem, the fix applied and the evidence of success.

Variant phrasings

Stripe subscription updated webhook fires before renewal payment confirmed brief uses unpaid status

The verbatim form searchers paste from the console, report or run log. Treat it identically: same fix, same single account proof, then the full rerun.

How to fix - Stripe subscription updated webhook fires before renewal payment confirmed brief uses unpaid status

The how to phrasing for the same failure in Stripe and the renewal brief. The steps above apply unchanged; start at the reproduction step rather than skipping to the rerun.

Stripe and the renewal brief troubleshooting for this failure

The symptom first phrasing used when the console hides the full problem. Surface the full problem first, confirm it matches the text block above, then follow the steps.

Why it happens

A subscription updated event fires when the renewal is created, before the charge settles, so a brief built on that event reports an unpaid status for a renewal that is simply still processing.

Edge cases

• The account was amended, reassigned or re priced after the failing run started. Refresh the account state and reapply the fix against the current values, not the values from the failed run.
• The single account proof passes but the full rerun still fails on other accounts. Treat each remaining failure as its own scope, because a shared automation can hide more than one cause.
• The source systems disagree on the correct value. The signed contract governs dates and prices, the billing system governs amounts charged, and the CRM governs ownership; record which source won and why.

Compatibility: Stripe and the renewal brief at current versions, plus the CRM, billing or CS platform the query names; no extra tooling beyond access to the source records needed to verify results.

Provenance

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

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

Thread query: Stripe subscription updated webhook fires before renewal payment confirmed brief uses unpaid status

TL;DR: Fix this in Stripe and the renewal brief by acting on the exact problem first: change the brief builder to read payment status from the invoice paid event in Stripe rather than the earlier subscription updated event, hold the brief status as pending until that paid event arrives, and regenerate the affected briefs once payment is confirmed. Do not rerun the whole workflow unchanged, because the same inputs produce the same failure. Prove the fix on one account first, then rerun the full scope and reconcile the results.