Skip to main content

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.

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, autoBillingDisabledReason changes to recurring_payment_errored. No further automatic charges occur.
warning

When all retries are exhausted, the subscription stays active but stops billing. It is not automatically cancelled. You may want to cancel it explicitly or prompt the customer to update their payment method.

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.