Guides

Recovering Subscription Payments

Enrol subscriptions in payment recovery and control what happens when a bills fail.

Payment recovery outlines how failed recurring payments can be automatically recovered.

This page covers how subscription bills from Acquired Billing can be enrolled in payment recovery 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 payment recovery. Support for recovering other recurring payments across the Acquired network is planned; each will be documented on its own page.

How recoveries behave — the strategies, lifecycle, and management described in Payment recovery — is the same regardless of where the failed payment came from.

Enrolling a subscription

Recovery 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 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.

How a failed bill becomes a recovery

When a bill payment fails, Acquired automatically creates a payment recovery for that bill. The recovery's order_id is the ID of the failed bill, which matches the order_id of any transaction associated to that bill. By sharing an order_id, the true success rate of a bill collection can be calculated.

Each bill produces at most one recovery record — if the same bill fails again, the existing recovery continues rather than a duplicate being created.

From there the recovery follows the strategy you assigned. See Payment recovery for the lifecycle and how to retrieve and manage it.

Failed payments and the subscription lifecycle

When a bill payment fails on an active subscription:

  • The failed bill is marked past_due and sent to payment recovery (if the subscription is enrolled), which retries it on the assigned strategy's schedule.
  • The subscription transitions to past_due.
  • While the failed bill transitions to past_due, the next bill for that subscription is created in draft status and held while recovery of the failed bill is still under way. A draft bill is not collected until its due date, given its status is not cancelled.
  • When payment recovery of a failed bill completes, the bill and subscription is updated accordingly:
    • If recovered, then the failed bill is updated from past_due to paid, and the subscription is updated from past_due to active
    • If unrecovered, then the failed bill is updated from past_due to unpaid, and the subscription remains in past_due or transitions to cancelled depending on the incomplete_bills_before_cancellation configuration (see Automatically cancelling after repeated failures below).

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.

📘

Note

If incomplete_bills_before_cancellation is not provided, it defaults to null and no auto-cancellation of subscriptions will be applied regardless of how many unpaid bills occur.

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
  }
}

The value N (which must be 1 or greater) is the number of consecutive unpaid bills you are willing to tolerate before cancelling the subscription. Before charging a new bill, Acquired checks the N most-recent bills; if all of them are still incomplete (unpaid), the new draft bill is voided and the subscription is cancelled — no further bills or recoveries are created for it.

  • If N is not provided, it defaults to null and no auto-cancellation of subscriptions will be 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 the subscription is cancelled.
📘

Note

Both recovery_strategy and incomplete_bills_before_cancellation can only be set when the subscription is created.