Invoice Statuses

Reference

Every invoice status, in the order it can appear.

Each invoice walks a defined state machine — from draft or unpaid, through confirmation, to either completed (success) or a terminal failure. The grouping below sorts every value by where it sits in that lifecycle.

Webhook event types Payment errors & refunds

Invoice statuses

Grouped by lifecycle phase

Pre-payment

The invoice exists, but no funds have arrived

draftSaved as a draft
The invoice has been created but is neither sent to a buyer nor scheduled for delivery. Visible to the merchant only.
scheduledQueued for delivery
The invoice is configured to be mailed out on a future date and will transition to unpaid when sent.
unpaidLive and awaiting payment
The invoice has been issued to the buyer. The payment address is active and the countdown to expiry has started.

In-flight

Payment detected — accruing confirmations

pendingAwaiting on-chain confirmations
Funds have been seen on-chain and are being watched until the chain's required confirmation depth is reached. Webhooks fire on every new confirmation — render progress with confirmations / requiredConfirmations from the payload.

Successful

Two steps — chain finality, then merchant credit

paidConfirmed — CoinPayments holds the funds
Required confirmations have been received and the funds are with CoinPayments, scheduled for payout to the merchant. Do not release goods yet — the credit has not landed in your balance.
completedCredited to merchant balance
Funds are reflected in the merchant balance. This is the terminal success state — the safe trigger for releasing goods or fulfilling the order.

Unsuccessful

Terminal — the invoice will not be paid

cancelledCancelled by the merchant
The merchant cancelled the invoice. Any funds already on-chain at the time of cancellation enter the automatic refund flow.
timedOutExpired without payment
The payment window closed before sufficient confirmations were received. Triggers the automatic refund flow for the buyer if any funds were already sent.
deletedDeleted
The invoice was removed. Should not appear in active workflows — listed here for completeness when reconciling historic records.

Wait for completed before releasing goods

paid means the chain has confirmed the payment and CoinPayments holds the funds — but the credit has not yet posted to your merchant balance. completed is the terminal success state, and the one you should key fulfilment off. Acting on paid exposes you to the gap between chain finality and merchant accounting.

Webhooks fire on every transition

You don't have to poll for these states. Subscribe to a client webhook and CoinPayments will push an event on every status change to your endpoint — plus one on each on-chain confirmation while pending. Verify the HMAC signature, key off the new status, and credit only on completed.

Casing differs between the API and webhooks

The REST Invoices API returns these statuses in camelCase (e.g. completed), but the client webhook payload delivers the invoice state in PascalCase (e.g. Completed). Compare case-insensitively. Each invoice payment also carries its own per-payment status, distinct from the invoice-level state.

Where to next?

Pick the most useful next step.

Client Webhooks

Receive a callback on every invoice state change.

Payment Errors & Refunds

Handle underpayments, overpayments, and timed-out invoices.