Invoices

Lists your invoices, newest first. Use status to reconcile a single bucket — UNPAID and PAST_DUE together are your receivables.

Creates the invoice in DRAFT. A draft is invisible to the customer and cannot be paid — publish it when you are ready.

The owning business comes from your API key, so there is no business_id in the body.

Totals are computed, not supplied. total_amount is the sum of price × quantity across the items, less discount_percent as a percentage. Sending a total of your own would let the displayed amount and the collectable amount disagree.

The total after discount must be at least 100 XAF — an invoice below that cannot be paid, and is better refused here than published and sent to a customer.

Where to send the customer: the response carries checkout_url, the page where the invoice is viewed and paid. Store it rather than building the URL yourself. A sandbox invoice's URL carries ?type=sandbox — keep the query string intact, or the page looks for the invoice in live data and 404s.

Cover image: call POST /files/upload-url first and pass the returned file_url as cover_image_url. URLs on any other host are rejected.

Idempotency: send an Idempotency-Key header. A retry with the same key replays the original response instead of creating a second invoice.

Fetches one invoice, including its items and any payments recorded against it. remaining_amount is what is still collectable.

Returns a URL to the invoice rendered as a PDF — the same document the customer receives by email.

The PDF is rendered when you ask for it rather than stored on the invoice, so it always reflects the invoice's current state: publish it, take a partial payment, call this again, and the document matches. That is also why it is a separate call and not a field on every read — listing 25 invoices should not render 25 PDFs.

A draft has no PDF worth sending; publish first.

Moves a DRAFT invoice to UNPAID, which is what makes it payable. Publishing is the point of no return: the amounts are fixed from here on.

Pass a channel to deliver it to the customer in the same call; omit it to publish quietly and send later with POST /invoices/{invoiceId}/send.

The response is the updated invoice plus published and, once the PDF has been rendered, pdf_url.

Delivers an already-published invoice by email or WhatsApp, with a link to pay it. Safe to call more than once — resending is the normal way to chase a late payment.

By default it goes to the customer_email / customer_phone on the invoice; override_email and override_phone redirect this one send without changing the invoice.

This needs the invoices:send scope, which invoices:write does not imply. Sending puts your brand in front of an arbitrary recipient, so it is the capability worth withholding from a key that only creates invoices.

Moves the invoice to CANCELLED so it can no longer be paid. The row and its history stay, which is what keeps your books reconcilable — there is no delete.

A partly-paid invoice can be cancelled; a fully PAID one cannot. Cancelling an already-cancelled invoice succeeds and returns it unchanged, so a retry is safe.