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 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. 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 reference for the full response schema.

Set the Retry Policy

Send a POST /v2/retry-policy 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.

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.