Bill Payment Webhooks

Each time a payment is attempted against a bill, Acquired sends a status_update webhook to the webhook_url configured on the subscription. This lets your system react to the outcome of every recurring payment in real time.

The status_update webhook is dispatched for every bill payment attempt, whether the payment succeeds or fails. For full detail on webhook headers, the webhook body schema, and how to validate the integrity of a webhook, refer to the webhook structure section of our Webhook Notifications guide.

📘
Note
While webhooks provide real-time updates, they can occasionally be interrupted or missed. We recommend also using GET /subscriptions/{subscription_id}/bills as a fallback to reliably confirm the status of a bill.

When is the webhook sent?

A status_update webhook is sent when a bill transitions from open following a payment attempt:

When the payment succeeds, the bill transitions to paid and a status_update with "status": "success" is sent.
When the payment fails, the bill transitions to past_due and a status_update reflecting the failure is sent.

See Bills for the full bill lifecycle and status transitions.

Identifying the subscription and bill

For payments taken by Acquired Billing, the status_update webhook_body includes two additional identifiers that link the payment back to the subscription and the specific bill it settles:

Field	Type	Description
`subscription_id`	string	ULID of the subscription the payment belongs to.
`bill_id`	string	ULID of the bill the payment settles.

Use these values to reconcile the webhook against the subscription and bill in your own system.

📘
For payments made by the Retry Engine while a bill is in recovery, the webhook also carries a recovery_id — see Recovery Payment Webhooks.

Examples

Successful payment — the bill transitions to paid:

{
  "webhook_type": "status_update",
  "webhook_id": "019ecfe6-0fc0-702a-9e64-66aadb1c8c34",
  "timestamp": 1781604421,
  "webhook_body": {
    "transaction_id": "019ecfe6-0e57-71a0-853c-4531e3fa33e1",
    "order_id": "01KV7YAHHWA4QS5RKMR4FSQRCA",
    "status": "success",
    "subscription_id": "01KV7YAB5GMD32H2A2DHZ6FKZ7",
    "bill_id": "01KV7YAHHWA4QS5RKMR4FSQRCA"
  }
}

Declined payment — the payment attempt failed and the bill transitions to past_due:

{
  "webhook_type": "status_update",
  "webhook_id": "019ecfe6-1a2b-702a-9e64-66aadb1c8c34",
  "timestamp": 1781604481,
  "webhook_body": {
    "transaction_id": "019ecfe6-1b3c-71a0-853c-4531e3fa33e1",
    "order_id": "01KV7YAHHWA4QS5RKMR4FSQRCA",
    "status": "declined",
    "subscription_id": "01KV7YAB5GMD32H2A2DHZ6FKZ7",
    "bill_id": "01KV7YAHHWA4QS5RKMR4FSQRCA"
  }
}

📘
What happens after a decline depends on your recovery strategy
Whether a declined bill payment is retried is governed by the recovery_strategy set in the payment_failure_configuration object on your Create Subscription request:

No strategy set — if payment_failure_configuration is omitted, or recovery_strategy is "none", no further payment attempt is made after a decline. The bill remains past_due.

Strategy set — if a valid recovery_strategy is provided, the failed bill is enrolled in the Retry Engine and automatically retried according to that strategy. Each retry sends its own status_update webhook, additionally carrying a recovery_id.

See Recovering subscription payments for how to configure recovery, and Recovery Payment Webhooks for the retry webhooks.

Configuring the webhook URL

The webhook_url can be set on the subscription. It can be supplied when you create a subscription, or — when activating via Components — persisted to the subscription from the webhook_url on the payment session. The stored value is used for the status update callback on every recurring payment.