Automate payment retries

Payments can fail for a number of reasons, but many of them are recoverable. Stripe Billing can automatically retry failed subscription and invoice payments for you.

To configure subscription retries in your Dashboard, go to Billing > Revenue recovery > Retries. For one-time invoice retries, go to Advanced invoicing features under Settings > Billing > Invoices.

Stripe recommends using Smart Retries, but you can also create a custom retry schedule.

Payment method ordering

When retrying, Stripe uses the first available payment method in this list, in this order:

When you update payment methods after a failed payment attempt, update the field where the previous payment failed. For example, if a subscription has a default_payment_method, but you only update customer.invoice_settings.default_payment_method, Stripe continues to retry on the subscriptions default_payment_method.

Smart Retries

Using AI, Smart Retries chooses the best times to retry failed payment attempts to increase the chance of successfully paying an invoice. The AI model behind Smart Retries uses time-dependent, dynamic signals, such as:

• The number of different devices that have presented a given payment method in the last N hours.
• The best time to pay (payments made for debit cards in certain countries might be slightly more successful at 12:01 AM in local time zones).

Stripe uses this information to assess when to retry payments. We continuously learn from new purchaser behaviors and transactions, which provide for a more targeted approach over traditional rules-based payment retry logic.

Smart Retries reattempts the charge according to your specifications for the number of retries and the maximum duration. You can set the Smart Retry policy to retry payment a specific number of times within a time period: 1 week, 2 weeks, 3 weeks, 1 month, or 2 months. The recommended default setting is 8 tries within 2 weeks. You can also use automations to create different retry policies for different customer segments.

You can override this behavior by disabling Smart Retries and defining your own custom retry rules. When you enable dunning, the next_payment_attempt attribute indicates when the next collection attempt will be.

Webhook events

For both Smart Retries and custom retry schedules, Stripe reattempts the charge according to your specified schedule. Use the invoice.payment_failed webhook to receive subscription payment failure events and retry attempt updates.

The attempt_count attribute on the invoice.payment_failed webhook indicates how many attempts have been made so far. If a failure returns a hard decline code, we cant retry invoice payment without a new payment method. Retries continue to be scheduled, and attempt_count continues to increment, but retries only execute after detecting a new payment method. Unexecuted retries dont create a new Charge.

The next_payment_attempt attribute on the invoice indicates the date when Stripe will attempt the next collection. For automations users, next_payment_attempt is no longer set in invoice.payment_failed webhooks but is set in invoice.updated webhooks.

Hard decline codes

Stripe cant automatically retry a payment if the card issuer returns any of these hard decline codes:

• incorrect_number
• lost_card
• pickup_card
• stolen_card
• revocation_of_authorization
• revocation_of_all_authorizations
• authentication_required
• highest_risk_level
• transaction_not_allowed

For these failures, the scheduled retries continue but the payment only executes if you obtain a new payment method.

Custom retry schedule

You can also modify the retry schedule with custom rules. You can configure up to three retries, each with a specific number of days after the previous attempt.

You can use the invoice.payment_failed event to monitor subscription payment failure events and retry attempt updates. After a payment attempt on an invoice, its next_payment_attempt value is set using the current subscription settings in your Dashboard.

If recovery fails, the subscription transitions according to your settings. The options are:

After the final payment attempt, we make no further payment attempts. Changing your subscription settings only affects future retries.

Retry local payment methods

Stripe can automatically retry failed payments made with local payment methods. Use the Local payment methods section for recurring subscription invoices, one-off invoices, or both, to turn on retries.

By default, Stripe doesnt automatically retry failed payments made with local payment methods. To enable automatic retries for local payment methods, use the corresponding settings in the following table: