Smart Retries

Billing Scale

Using machine learning, Smart Retries chooses optimal times to retry failed payment attempts to increase the chance of successfully paying an invoice. The machine learning system behind Smart Retries uses hundreds of time-dependent, dynamic signals, such as:

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

Based on a combination of these factors, Stripe intelligently assesses when to retry payments. We continuously learn from new purchaser behaviors and transactions, which provide for a more optimized approach over traditional rules-based payment retry logic.

The Smart Retries feature attempts to retry the customer’s charge up to eight times within a customizable time frame and supports cards. 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.

Retry policies Beta

The Dashboard lets you configure Smart Retries that apply to all your payments. Use retry policies for more control over how Smart Retries handle subsets of failed payments or specific ones.

With the Retry Policy API, use:

• smart_retry[max_retry_count] to set how many times to retry, up to a maximum of 8 times.
• smart_retry[retries_end_after_days] to set the length of time to retry, up to a maximum of 60 days.

You can also maintain more than one retry policy and list all that are available for use.

Default retry policy

With the default settings, Stripe retries up to 4 times over a maximum period of 21 days. Here’s what those settings look like:

• smart_retry[retries_end_after_days]=21
• smart_retry[max_retry_count]=4

GET /v1/retry_policies/

{
  "object": "list",
  "url": "/v1/retry_policies",
  "has_more": false,
  "data": [
    {
      "id": "retrypolicy_123",
      "description": "retry_policy_default",
      "type": "smart_retry",
      "smart_retry": {
        "retries_end_after_days": 21,
        "max_retry_count": 4
      }
      "livemode": true,
    }]
}

Multiple retry policies

Creating more retry policies can be useful if you have multiple service offerings (for example, annual subscriptions and monthly subscriptions) and want to manage their retries differently. The following example creates a new policy that retries 8 times within 60 days:

POST /v1/retry_policies
  type='smart_retry',
  smart_retry[retries_end_after_days]=60,
  smart_retry[max_retry_count]=8,
  description="retry_policy_annual"

{
  "id": "retrypolicy_987",
  "description": "retry_policy_annual",
  "type": "smart_retry",
  "smart_retry": {
    "retries_end_after_days": 60,
    "max_retry_count": 8
  },
  "livemode": true
}

Specify which retry policy to use

You can specify which retry policy to associate with your subscription customers. This change affects new customers who sign up for your subscription. If you only have one retry policy, Stripe automatically defaults to it. For example:

POST /v1/subscriptions
  ...
  retry_settings[enabled]=true // If Smart Retries is on in the Dashboard, the default is true.

{
  "id": "monthly_subscriptions",
  ...
  "retry": {
    "enabled": true,
    "policy": "retrypolicy_123"
  },
  "livemode": true,
  ...
}

If you have multiple retry policies, use the retry policy’s id to specify which one to use. For example, let’s say you have different retry policies for monthly and annual subscriptions, and the retry policy id for your annual subscriptions is retrypolicy_987. To use this policy for your new annual subscribers, call the API with:

POST /v1/subscriptions
  ...
  retry_settings[enabled]=true
  retry_settings[policy]=retrypolicy_987
  expand[]="retry_settings[policy]"

{
  "id": "annual_subscriptions",
  ...
  "retry": {
    "enabled": true,
    "policy": {
      "id": "retrypolicy_987",
      "description": "retry_policy_annual",
      "type": "smart_retry",
      "smart_retry": {
        "retries_end_after_days": 60,
        "max_retry_count": 8
      }
    }
    "livemode": true
  },
  ...
}

Update a retry policy

You can change the retry schedule of an existing policy. For example, let’s say you have a policy that retries 8 times within 60 days for a failed payment. After running some analytics, you realize you can achieve better recovery results with 45 days, and decide to update the policy:

POST /v1/retry_policies
  id='retrypolicy_987',
  type='smart_retry',
  smart_retry[retries_end_after_days]=45,
  smart_retry[max_retry_count]=8

{
  "id": "retrypolicy_987",
  "description": "retry_policy_annual",
  "type": "smart_retry",
  "smart_retry": {
    "retries_end_after_days": 45,
    "max_retry_count": 8
  }
  "livemode": true
}