In the Stripe Dashboard, navigate to Billing → Settings → Smart Retries and enable the Smart Retries feature, which uses Stripe's ML model to pick optimal retry times for failed invoices.
Optionally configure a custom retry schedule by going to Billing → Settings → Manage failed payments and specifying the number of retry attempts and intervals (e.g., retry at 3 days, 5 days, 7 days after failure).
Set the `collection_method` on your subscriptions to `charge_automatically` to enable automatic invoice charging and retry behavior.
Configure the subscription's `payment_settings.payment_method_types` to include only the payment method types eligible for automatic retries (primarily card — ACH and other methods have different retry behaviors).
Subscribe to the Stripe `invoice.payment_failed` and `invoice.payment_action_required` events via a webhook endpoint to detect failures and trigger supplementary dunning actions (emails, customer portal prompts).
Set `payment_behavior` on subscription creation or update to `default_incomplete` or `allow_incomplete` depending on whether you want Stripe to attempt the first payment immediately or defer — verify the correct value for your use case in Stripe docs.
Known gotchas
Smart Retries and the manual retry schedule are mutually exclusive — enabling Smart Retries disables the manual schedule. Confirm in the Dashboard which mode is active; the UI may show both settings simultaneously and it is easy to misread which is active.
Stripe Smart Retries respect card network retry guidelines for merchant-initiated transactions. Retrying outside allowed windows may result in declines or increased dispute rates. Do not implement an additional retry layer on top of Smart Retries that bypasses these windows.
When an invoice enters the `past_due` state after all retries are exhausted, the associated subscription moves to `past_due` or `unpaid` (depending on your `payment_settings.payment_failure_behavior` setting). Handle both subscription statuses in your application logic.
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp