# Invoices

> Generate itemized invoices payable in crypto.

Section: Accepting Payments
Source: https://coincircuit.io/docs/guides/invoices/
Interactive version: https://coincircuit.io/api-reference?tab=guides&guide=invoices

## API reference

- POST `/api/v1/invoices`: [Create an invoice](https://coincircuit.io/api-reference/#tag/invoices/POST/api/v1/invoices)
- GET `/api/v1/invoices/reference/{reference}`: [Retrieve an invoice](https://coincircuit.io/api-reference/#tag/invoices/GET/api/v1/invoices/reference/{reference})
- GET `/api/v1/invoices`: [List invoices](https://coincircuit.io/api-reference/#tag/invoices/GET/api/v1/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](https://coincircuit.io/images/features/invoices.webp)

## How it works
1. Create the invoice with `POST /api/v1/invoices`.
2. Share the invoice link with your customer.
3. Track payment with `GET /api/v1/invoices/reference/{reference}` or the `invoice.paid` webhook.
4. 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](https://coincircuit.io/images/features/invoices-builder.webp)

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

![Invoice page with QR payment](https://coincircuit.io/images/features/invoices-pay.webp)

## 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.