Invoices

Generate itemized invoices payable in crypto.

Open the interactive version or read this guide as markdown.

API reference

POST /api/v1/invoices: Create an invoice
GET /api/v1/invoices/reference/{reference}: Retrieve an invoice
GET /api/v1/invoices: List invoices

An invoice bills a customer for itemized work. You list each line item with its quantity and price, CoinCircuit totals them, and the customer gets a page to pay in the crypto they choose. Invoices take partial payments, and a webhook tells you when one is settled in full.

CoinCircuit invoice — line items, amount due, and pay link

How it works

Create the invoice with POST /api/v1/invoices.
Share the invoice link with your customer.
Track payment with GET /api/v1/invoices/reference/{reference} or the invoice.paid webhook.
List all invoices with GET /api/v1/invoices.

Request fields

Field	Type	Required	Description
`items`	array	Yes	Line items. Each item requires `name`, `quantity`, and `unitPrice`; `description` and `unit` are optional.
`currency`	string	Yes	`NGN` or `USD`.
`description`	string	Yes	Shown to the customer on the invoice.
`expiresAt`	string	Yes	ISO 8601 expiry date, up to 5 days from creation.
`customer`	object	Yes	`email` and `firstName` are required.
`reference`	string	No	Your invoice reference. Auto-generated if omitted.
`asset` / `chain`	string	No	Lock the cryptocurrency and network for payment.
`periodStart` / `periodEnd`	string	No	Billing period dates for recurring invoices.
`successUrl` / `cancelUrl`	string	No	HTTPS redirect URLs after payment or cancellation.
`metadata`	object	No	Key-value data returned in webhooks.

Add items line by line in the dashboard, each with a quantity and unit price:

Invoice builder with line items

The customer sees a page with the amount due, line items, and a QR code:

Invoice page with QR payment

Webhook events

Event	Sent when
`invoice.updated`	A partial payment is received. Compare `amountPaid` to `amount` to track progress.
`invoice.paid`	The invoice is paid in full. Deliver the goods or service on this event.
`invoice.expired`	The invoice expired before full payment.

Use cases

B2B billing and milestone payments
Client invoicing for services
Subscriptions and renewals

Invoices accept partial payments. Store your own reference in metadata to match payments to your records.