Integrating Billing & Recover

This page lays out the integration journey for a merchant adding Acquired Recover to their subscription billing. The steps below are ordered the way you will tackle them: the first two are build-time decisions made when you create a subscription, and the rest are run-time concerns once bills start failing and recoveries are created.

📘

Before you start

Recovery currently feeds from subscription bills only. See Recovering subscription payments for the underlying behaviour, and Payment recovery for how a recovery behaves once created. This page assumes you already have Acquired Billing subscriptions integrated.

1. Enrol a subscription in recovery

Payment recovery is opt-in per subscription and is enabled at subscription-creation time. Add the payment_failure_configuration object to your Create Subscription request — its presence (with a valid recovery_strategy) is what enrols the subscription and ensures any failed bill payments from that subscription are automatically recovered:

{
  "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". A failed bill payment on an unenrolled subscription is not automatically recovered.

2. Set the recovery strategy and auto-cancel policy

With enrolment in place, the payment_failure_configuration object carries the two settings that govern how hard and how long Acquired tries on your behalf. incomplete_bills_before_cancellation can only be set at creation, but recovery_strategy can be changed later via PATCH /subscriptions/{subscription_id}/payment_failure_configuration — letting you enrol a subscription that started out unenrolled, switch strategy, or unenrol with "none":

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

recovery_strategy — the named schedule that determines how and when a failed bill is retried. Use the exact strategy name supplied during onboarding; an unrecognised name is rejected when the subscription is created. See Recovery strategies.

incomplete_bills_before_cancellation — your tolerance policy for repeated failures. The value N (must be 1 or greater) is the number of consecutive unpaid bills you will tolerate before the subscription is cancelled:

See Automatically cancelling subscription after repeated failures for exactly how the check is applied before each new bill.

3. Retrieve the status and details of a recovery

Once a bill payment fails, Acquired creates a payment recovery and works the strategy automatically — no polling is required to keep it running. You can retrieve recoveries to report on outcomes and surface recovery state in your own dashboards.

Read these two fields together to know where a recovery stands:

• status — recovering (in progress), recovered (collected), unrecovered (ended without collecting), or cancelled (cancelled via the API). All but recovering are terminal.
• termination_reason — null while in progress; once terminal it explains why it ended (for example payment_successful, max_retries_exceeded, advice_do_not_retry, or recovery_cancelled). See Recovery Lifecycle for all reasons.

{
  "id": "01JE3X4Y5Z6A7B8C9D0E1F2G3H",
  "order_id": "01HNY4G8G8P4E1T4YJ9N8B1Z9M",
  "customer_id": "c3e06b6f-bb52-4b2c-81a3-899860652240",
  "status": "recovering",
  "amount": 19.99,
  "currency": "GBP",
  "recovery_strategy": "example_strategy",
  "termination_reason": null,
  "created_at": "2025-11-17T17:00:00Z",
  "next_action_scheduled_date": "2025-11-20T09:00:00Z",
  "payment_retry_attempt_count": 1
}

If a payment is settled outside the recovery pipeline, or you need to stop one early, use the management endpoints (/cancel and /recovered) — both valid only while the recovery is recovering. See Retrieving and managing recoveries for the full lifecycle.

4. How to treat a subscriber during Recovery

See failed payments and the subscription lifecycle for what happens to subscription and bill statuses when a payment recovery is in progress or completes.

When a payment is being recovered, the subscription status is updated to reflect its current state. Retrieving the current subscription status allows you to treat the subscriber accurately in your systems.

5. Reconcile a recovery with the bill payment it came from

A recovery is always tied back to the payment that triggered it through a shared order_id. This is the key to reconciliation in your own systems:

• A recovery's order_id is the ID of the failed bill it is recovering.
• That same order_id is shared by every transaction attempted against that bill.

Because the bill, its transactions, and the recovery all carry the same order_id, you can stitch the full picture together — and, by counting successful versus failed attempts under one order_id, calculate the true success rate of collecting that bill.

Two further guarantees make reconciliation predictable:

• At most one recovery per bill. If the same bill fails again, the existing recovery continues rather than a duplicate being created — so an order_id maps to a single recovery record.
• Outcomes flow back to the bill and subscription:
  • A recovered recovery moves the failed bill from past_due to paid and reactivates the subscription to active
  • an unrecovered recovery marks the bill unpaid (a terminal status — collection has stopped) and leaves the subscription past_due (or cancelled, per your auto-cancel policy). See Failed payments and the subscription lifecycle.

These outcomes apply only while the bill is still past_due: if you manually mark it paid or void while the recovery is running, your change stands and the recovery outcome will not overwrite it.

Cancelling a recovery is the exception: because it is a manual action, it does not automatically flow an outcome back to the bill or subscription. See Manually cancelling a recovery.

📘

Tip

To find a recovery from a known bill, call GET /payment_recoveries filtered by order_id. To go the other way, the order_id on a recovery is the bill ID you started from.

6. Cancel a recovery

If a payment is settled outside the recovery pipeline, or you otherwise want to stop retrying, cancel the recovery with POST /payment_recoveries/{recovery_id}/cancel — valid only while it is recovering. It moves to cancelled (recovery_cancelled).

Cancelling does not automatically update the Bill or Subscription. See Manually cancelling a recovery for the options available and how they interact with your auto-cancel policy.