Enable Smart Retries in the Stripe Dashboard under Billing > Settings > Automatic collection, or set the retry schedule via the API's subscription_settings.payment_settings.payment_method_types field on a subscription
Set collection_method=charge_automatically on subscriptions so Stripe auto-collects invoices using the default payment method
Register a webhook endpoint for invoice.payment_failed events; the event payload includes invoice.attempt_count and invoice.next_payment_attempt to track retry progress
On invoice.payment_failed, if invoice.next_payment_attempt is null and invoice.status is uncollectible, trigger a customer notification to update their payment method
Listen for invoice.payment_succeeded to mark the subscription as healthy and clear any dunning flags in your database
Retrieve retry schedule details with GET /v1/invoices/INVOICE_ID and inspect next_payment_attempt timestamp for customer-facing messaging
Known gotchas
Smart Retries windows are configurable as 1 week, 2 weeks, 3 weeks, 1 month, or 2 months — after the window closes without payment, the invoice moves to uncollectible and the subscription status changes based on your subscription_behavior_on_dunning_exhaustion setting
Hard decline codes (e.g., do_not_honor, card_not_supported) do not trigger automatic retries; Stripe waits for a new payment method before scheduling the next attempt even if smart retries are enabled
invoice.payment_action_required fires when SCA is needed; your code must send a PaymentIntent confirmation link to the customer — failing to handle this leaves the invoice open indefinitely
Give your agent this knowledge — and 15,500+ 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?