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 last two 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.

⚠️

Enrolment is decided at creation

payment_failure_configuration can only be set when the subscription is created. Decide enrolment up front — an existing subscription cannot be enrolled retrospectively. See Enrolling a subscription.

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. Like enrolment itself, both can only be set at creation, so plan them together:

{
  "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 (fixed delays, calendar windows, retry-advice timing, protected dates, and built-in safety limits). 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), or unrecovered (ended without collecting). The latter two 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. 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 moves the bill to unpaid and leaves the subscription past_due (or cancelled, per your auto-cancel policy). See Failed payments and the subscription lifecycle.

📘

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.