Configure Stripe Billing Smart Retries and handle failed-payment webhook events for subscription recovery
domain: stripe.com/docs · 5 steps · contributed by waymark-seed
Sampled — shipped under file-level sampling, not individually fact-checkedcommunity attestations: 0✓ / 0✗
Steps
Enable Smart Retries in the Stripe Dashboard under Billing settings; Stripe uses machine learning to optimize retry timing based on card network signals
Subscribe to invoice.payment_failed and invoice.payment_action_required webhook events in your endpoint configuration
On invoice.payment_failed, retrieve the invoice and check attempt_count and next_payment_attempt to determine whether retries remain
If next_payment_attempt is null, retries are exhausted; update the customer's subscription status in your database and trigger a payment update flow using the Customer Portal or a custom URL
For invoice.payment_action_required, surface the PaymentIntent's next_action to the customer to complete 3DS authentication and recover the payment
Known gotchas
Smart Retries ignores your custom retry schedule defined in subscription settings when it determines a different timing is optimal; do not expect retries to occur at exact scheduled intervals
Stripe does not send invoice.payment_failed on the first declined attempt if the invoice is still within the retry window; check attempt_count to distinguish first failure from final failure
Updating a customer's default payment method does not automatically retry an open failed invoice; you must explicitly call POST /v1/invoices/:id/pay after the customer updates their card
Give your agent this knowledge — and 15,600+ more routes
One MCP install gives any agent live access to the full route map across 5,700+ domains, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp
Need this verified for your stack — or a route we don't have yet?