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

• API access with the RETRY_POLICY_CREATE permission.
• 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 /retry-policies 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.

View the Default Retry Policy

Every merchant account has a default retry policy. ODUS uses this policy for any subscription that does not have a specific policy assigned.

To retrieve it:

GET /retry-policies/default

The response includes the policy's id, title, isEnabled, and the full list of steps. Note the id — you will need it to update the policy.

See the GET /retry-policies/default reference for the full response schema.

Create a New Retry Policy

Send a POST /retry-policies request with a title and at least one step:

{
  "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"
    }
  ]
}

The response includes the new policy's id (for example, rp_2QutFDO5YritcVsdlPkQkD35f61). Store this ID if you need to update the policy later.

Update a Retry Policy

Send a POST /retry-policies/{id} request with the complete updated list of steps. This replaces all existing steps on the policy.

{
  "title": "Updated recovery schedule",
  "steps": [
    {
      "position": 1,
      "retryDelay": 1,
      "useInitialGateway": true
    },
    {
      "position": 2,
      "retryDelay": 5,
      "useInitialGateway": true
    }
  ]
}

To update the default retry policy, first retrieve its id using GET /retry-policies/default, then send the update to POST /retry-policies/{id}.

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.