Recovery Payment Webhooks

When the Retry Engine attempts to recover a failed bill payment, Acquired sends a status_update webhook to the webhook_url configured on the subscription — the same endpoint used for the original bill payment. This lets your system react to the outcome of each recovery attempt in real time.

Because a recovery is always tied to a subscription and the bill it is recovering, the webhook_body carries all three billing identifiers — subscription_id, bill_id, and recovery_id.

For full detail on webhook headers, the body schema, and how to validate the integrity of a webhook, refer to the webhook structure section of our Webhook Notifications guide.

Telling a recovery attempt apart from the original attempt

The presence of recovery_id is what distinguishes a recovery payment from the bill's original payment attempt:

If a status_update for a subscription payment includes a recovery_id, it was taken by the Retry Engine. Use it to look up the recovery record directly with GET /payment_recoveries/{recovery_id}, rather than relying on the shared order_id alone.

When is the webhook sent?

A status_update is sent for each payment attempt the Retry Engine makes against a past_due bill:

• A successful recovery moves the bill from past_due to paid and reactivates the subscription — the webhook carries "status": "success".
• A failed attempt leaves the bill past_due; the recovery continues its strategy or, once exhausted, the outcome flows back to the subscription per your auto-cancel policy.

See Recovering subscription payments for how recovery outcomes map to bill and subscription statuses.

Example

A status_update webhook sent when a recovery attempt succeeds:

{
  "webhook_type": "status_update",
  "webhook_id": "bc25b699-ffb1-40d5-b508-f6a28aeb18eb",
  "timestamp": 32908394083,
  "webhook_body": {
    "transaction_id": "1d0483a7-6f84-4784-9fba-3c7553847be0",
    "status": "success",
    "order_id": "01JC4Z2BC9J1V1B8YHR4E0X4T5",
    "subscription_id": "01JC4Z1YR25RSAFVHYY7GA1BRQ",
    "bill_id": "01JC4Z2BC9J1V1B8YHR4E0X4T5",
    "recovery_id": "01JC4Z2Y0Q4E7Q0YV5D3M6W9KA"
  }
}