Webhook events and order statuses

Each webhook event matches an order status. BillPro sends the event when an order moves into that status. This page maps each event to its status, the usual cause, and the order types it applies to.

For full status definitions, see Order status and Order flow.

Events by status

Event	Status	Meaning	Usual cause
`order.draft`	`Draft`	Created, nothing collected yet. New orders start here.	You create or save an order. If you create it with a payment link, you receive `order.draft` and then `order.pending`.
`order.pending`	`Pending`	Waiting for the first payment.	You send a payment link, and the customer hasn't paid or registered a card yet.
`order.registered`	`Registered`	The card is saved and the first payment is waiting.	The customer's card is saved before the first payment is collected.
`order.rejected`	`Rejected`	Declined because of a card problem. Retrying won't help.	The first payment or card registration by virtual terminal is declined.
`order.cancelled`	`Cancelled`	Cancelled. Nothing more is collected.	You cancel the order. You can cancel an order in any status except `Complete` and `Cancelled`.
`order.active`	`Active`	Collecting payments on its schedule.	The first payment or card registration is approved on a recurring order. Or a pre-authorised amount is approved on a single-payment order.
`order.failed`	`Failed`	A payment was declined but can be retried.	A scheduled payment is soft declined, for example for insufficient funds.
`order.suspended`	`Suspended`	Stopped after a failed payment, on an order that had already collected a payment.	A payment is hard declined, for example because the account is closed. The card must be replaced. Or a payment is soft declined on an order that isn't an instalment, and auto-retry is off for that payment.
`order.paused`	`Paused`	Paused by the merchant. Payments restart when it's resumed.	You pause a subscription.
`order.review`	`Review`	Needs a manual check, for example after an overpayment.	The customer has paid more than the order's value. Or an instalment order runs past its number of payments, or a subscription collects a payment after its end date.
`order.complete`	`Complete`	Nothing more is due.	The full amount is collected, a pre-authorisation is captured or reversed, or you mark a live order as complete. For a registration-only order, the card is saved and nothing is collected.

An order can move into the same status more than once, for example Active → Failed → Active after a retry succeeds. You receive an event each time.

Status flows by order type

Draft, Pending and Rejected apply to all order types, before the first payment or card registration is approved. Registered can appear before Active when the card is saved before the first payment is collected. Any order can become Cancelled unless it's already Complete.

Single payment

Paid straight away: Draft → Pending → Complete, or Draft → Complete by virtual terminal.
With Pre-authorise: Draft → Active → Complete when you capture or reverse the amount. See Authorise and capture payments.

Single-payment orders don't use Failed, Suspended, Paused or Review.

Instalment

Draft → Pending → Active → Complete when the full amount is collected.

While live, an instalment order can move to Failed (soft decline), Suspended (hard decline) or Review (overpaid, or past its number of payments). An instalment stays Failed even when auto-retry is off.

Subscription

Draft → Pending → Active. A subscription stays active until it's cancelled. It becomes Complete when you mark it complete, or when the customer cancels it in the order portal. See Cancel a subscription.

While live, a subscription can move to Failed, Suspended, Paused or Review (collected after its end date). Only subscriptions can be paused. See Pause a subscription.

Metered

Draft → Pending → Active, then Complete when you mark it complete.

While live, a metered order can move to Failed or Suspended.

Payments, scheduled payments and refunds

Webhooks report the order status only. They don't report the status of individual scheduled payments, billing events or refunds.

A payment reaches you only when it changes the order status. For example, a declined scheduled payment can move the order from Active to Failed, and you receive order.failed. A refund that doesn't change the order status doesn't send a webhook.

Scheduled payments have their own statuses, and some use the same names as order statuses, such as failed and complete. Treat the two lists separately. To check scheduled payments after an event, use the API. See Billing events and scheduled payments.