Recovering Subscription Payments

Retry Engine overview outlines how failed recurring payments can be automatically recovered.

This page covers how subscription bills from Acquired Billing can be enrolled in the Retry Engine and what happens to the subscription when its payments fail.

📘
More failed recurring payment sources are coming!
Subscription bills are currently the only payments that feed the Retry Engine. Support for recovering other recurring payments across the Acquired network is planned; each will be documented on its own page.
How retries behave — the strategies, lifecycle, and management will be the same regardless of where the failed payment came from.

Objects and statuses

A failed subscription payment touches four objects, all tied together :

subscription → bill → transaction → payment recovery

Each bill, its transactions, and the recovery all carry the same order_id, allowing you to reconcile the full picture in your own systems — see How a failed bill becomes a recovery for more.

See Subscription statuses in the Managing Subscriptions guide
See Bill statuses in the Bills guide
For recovery statuses (recovering / recovered / unrecovered) and termination_reason, see The recovery lifecycle

Enrolling a subscription in the Retry Engine

The Retry Engine is opt-in per subscription and is configured at subscription-creation time using the payment_failure_configuration object on the Create Subscription request.

Set recovery_strategy to the name of the strategy you want to apply:

{
  "customer": {
    "customer_id": "c3e06b6f-bb52-4b2c-81a3-899860652240"
  },
  "product": { "name": "Pro Plan" },
  "price": { "amount": 19.99, "currency": "GBP" },
  "payment_failure_configuration": {
    "recovery_strategy": "example_strategy"
  }
}

To leave a subscription unenrolled, omit payment_failure_configuration or send "recovery_strategy": "none". In that case, a failed bill payment is not automatically recovered.

recovery_strategy can be updated after creation via PATCH /subscriptions/{subscription_id}/payment_failure_configuration, letting you enrol a subscription that started out unenrolled, switch to a different strategy, or unenrol with "none".

📘
Recovery strategies
A recovery strategy is a named schedule that determines how and when failed payments are recovered — see Recovery strategies. The set of strategies available to you, and their names such as example_strategy, is provided as part of your onboarding. An unrecognised name is rejected when the subscription is created.

Failed payments and the subscription lifecycle

Statuses at a glance — what happens to Subscription and Bill statuses in different payment situations, and how to treat the subscriber accordingly.

Situation	Subscription status	Bill status	Recovery status	Treat the subscriber as...
Collecting normally — "healthy cycle"	`active`	`paid`	—	Full access
Payment failed, being recovered	`past_due`	`past_due`	`recovering`	Subscription at risk — your call whether to allow access while payment is being recovered
Recovered	`active`	`paid`	`recovered`	Resolved — nothing to do
Recovery gave up / ended unsuccessfully	`past_due` (or `cancelled`)	`past_due`	`unrecovered`	Your call — put in dunning or restrict (let auto-cancel apply)

Recovery outcomes and Subscription/Bill statuses

Outcome	When it happens	Recovery	Bill	Subscription	What it means
Recovered	A recovery strategy succeeds	`recovering` → `recovered`	`past_due` → `paid`	`past_due` → `active`	Back to a healthy cycle — the next bill proceeds normally to its due date.
Unrecovered	The strategy ends with all attempts unsuccessful	`recovering` → `unrecovered`	`past_due` (stays)	`past_due` (stays) or → `cancelled`	The subscription is cancelled only when repeated consecutive failures hit your `incomplete_bills_before_cancellation` policy; otherwise it stays `past_due`. See Automatically cancelling subscription after repeated failures.

Automatically cancelling subscription after repeated failures

incomplete_bills_before_cancellation lets you define your own policy for when a subscriber is cancelled after their payments repeatedly fail — putting you in control of how much tolerance to give a failing subscriber.

Whether you want a strict "one strike and you're out" rule or a more lenient one that allows several missed payments before giving up, this single setting supports both. Set it on payment_failure_configuration at subscription creation:

{
  "payment_failure_configuration": {
    "recovery_strategy": "example_strategy",
    "incomplete_bills_before_cancellation": 3
  }
}

How it works

The incomplete_bills_before_cancellation check runs before charging each new bill — not at the moment a payment fails.
It reads the N most-recent prior bills for the subscription.
- A bill is counted as incomplete if its status is past_due or unpaid
- A bill is considered complete if its status is paid nor void.
If all N of those prior bills are incomplete, the subscription is cancelled and the upcoming due bill is voided.
A bill leaves the incomplete set only when it becomes paid (for example, a recovery succeeds) or void. This reduces the count and resets the tolerance window.
If incomplete_bills_before_cancellation is null, this check is skipped entirely.

Choosing a value

If N is not provided, it defaults to null and no auto-cancellation is applied, regardless of how many unpaid bills occur.
Set it to 1 for a strict policy: a single unpaid bill cancels the subscription.
Set it higher (for example, 3) for a more lenient policy: the subscriber is given more billing cycles — and recovery more chances to succeed — before cancellation.

Reconciling recovery attempts

A failed bill payment automatically creates one payment recovery, which then runs the strategy you assigned — see Payment recovery for its lifecycle and management.

Two properties matter for reconciliation:

Shared order_id — the recovery attempt's order_id is the failed bill's order_id, the same order_id carried by every transaction against that bill. Tie the attempts back to the bill to calculate its true collection success rate.
One recovery per bill — a repeat failure on the same bill continues the existing recovery; it never creates a duplicate.