# Configure a Payment Retry Policy

When a subscription renewal charge fails, ODUS automatically retries the charge according to the merchant's retry policy (also called a **recycle profile**). A retry policy defines a schedule of retry attempts, each with configurable delays and gateway options.

## Prerequisites

* A secret API key with the `retry_policy:update` permission to set the policy, and `retry_policy:read` to read it.
* The IDs of any gateway profiles you want to pin specific retry steps to.

## How a Retry Policy Works

A retry policy contains a list of **steps**. Each step represents one retry attempt. Steps are executed in order of their `position` value (lowest first). When a renewal payment fails, ODUS works through the steps one by one, waiting the configured `retryDelay` (in days) between each attempt.

Each step can either retry on the original gateway (`useInitialGateway: true`) or target a specific `gatewayProfile`. You can also set a `priceReductionPercentage` to lower the charge amount for that attempt. See the [`POST /v2/retry-policy`](https://docs.odus.com/docs/api/core/v2/retry-policy-controller-set) reference for the full parameter list.

note

Gateway selection only applies to card payments. For other payment methods such as PayPal or Apple Pay, ODUS always uses the initial gateway regardless of the step configuration.

### Payments that never reached a decision

Some failures mean the request stopped before the issuer could approve or decline it. These are the `authentication_unavailable` and `processor_rate_limited` [error codes](https://docs.odus.com/docs/guides/payments/error-codes.md). ODUS resends these payments before your retry policy starts:

* The payment is resent **unchanged**. It keeps the same amount, gateway and payment method. No step's `priceReductionPercentage` or `gatewayProfile` applies.
* ODUS resends it up to **three times**, about 1, 5 and 15 minutes apart. No resend is scheduled more than **30 minutes** after the first failure.
* These resends are not policy steps. While a resend is pending, `retry.attempts` does not change, and `retry.nextAt` shows when it is due. A resend that succeeds counts as one retry attempt, like a successful step, so `isRecovered` is `true`.
* If a resend succeeds, the payment succeeds as it would after any retry. If a resend fails for another reason, ODUS handles it like any other failed retry. If all three resends fail, ODUS continues with the policy step that was next. In both cases none of your steps is used up by the resends.

The same happens when a policy step fails with one of these codes: ODUS resends that step unchanged and then moves on to the following step.

Other codes with the `retry_immediately` strategy, such as `processor_timeout`, are never resent this way. Those payments may already have been processed, so ODUS waits for the policy's `retryDelay`.

## Your account has one retry policy

Your account has at most one retry policy, and ODUS applies it to every subscription renewal that fails. Until you set one, a failed renewal is not retried.

`GET /v2/retry-policy` and `POST /v2/retry-policy` both act on that one policy, so neither takes an ID.

## View the Retry Policy

```
GET /v2/retry-policy
```

The response includes the policy's `title`, `isEnabled`, and the full list of `steps`.

If you have not set a policy yet, the request answers `404`. Treat that as "no retry policy configured", not as a failure.

See the [`GET /v2/retry-policy`](https://docs.odus.com/docs/api/core/v2/retry-policy-controller-get) reference for the full response schema.

## Set the Retry Policy

Send a [`POST /v2/retry-policy`](https://docs.odus.com/docs/api/core/v2/retry-policy-controller-set) request with a `title` and at least one step. The same request creates the policy if you have none and replaces it if you do:

```
{

  "title": "Standard recovery — 3 attempts",

  "steps": [

    {

      "position": 1,

      "retryDelay": 3,

      "useInitialGateway": true

    },

    {

      "position": 2,

      "retryDelay": 7,

      "useInitialGateway": true,

      "priceReductionPercentage": 10

    },

    {

      "position": 3,

      "retryDelay": 14,

      "useInitialGateway": false,

      "gatewayProfile": "gwp_2QUGPTQo8As1cNIvgKlSFDxjJDd"

    }

  ]

}
```

Send the whole policy every time

A request replaces the policy, including every step. To change one step, send the `title` and the complete list of `steps` with that step changed. Steps you leave out are removed.

## Effect on the Subscription Lifecycle

When a subscription renewal fails, ODUS sets `autoBillingEnabled: false` with `autoBillingDisabledReason: latest_invoice_retrying` and begins executing the retry steps.

* If a retry **succeeds**, `autoBillingEnabled` is restored to `true` and normal billing resumes.
* If all retry steps are **exhausted**, ODUS voids the invoice and cancels the subscription. You receive a `subscription.cancelled` event.

For the full picture of subscription states and how retries fit the billing lifecycle, see [Subscription Lifecycle](https://docs.odus.com/docs/guides/subscriptions/subscription-lifecycle.md).

## Configure via the Dashboard

1. Go to **Settings** → **Recycle Billing**.

2. If no profile exists yet, click **Add**.

3. Enter a **Title** for the profile.

4. Under **Billing rules**, click **New rule** to add a retry step.

5. For each rule, configure:

   <!-- -->

   * **Wait period** — number of days to wait before this attempt
   * **Price reduction (%)** — optional percentage to reduce the charge amount
   * **Gateway** — select **Initial Gateway** to retry on the original gateway, or choose a specific gateway profile from the list

6. Drag rules to reorder them. The topmost rule is executed first.

7. Click **Add** (or **Update** if editing an existing profile) to save.

A profile can have up to 12 rules.