Create a draft invoice

Authorization

OAuth2PasswordBearer

AuthorizationBearer <token>

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

What an invoice is made of. IN-302.

Totals are not here: subtotal_minor, tax_minor and total_minor are derived from the lines and returned on the invoice. Sending a total that disagrees with the lines is the one way to make an invoice that cannot be reconciled, so there is no field to send it in.

number*Number

Your invoice number. Yours rather than ours, because it is what your customer and your accountant will both quote. Unique per business — reusing one is a 409.

Length1 <= length <= 64

Example"INV-2026-0042"

customer_name*Customer Name

Who is being invoiced, as it should appear on the invoice.

Length1 <= length <= 200

Example"Kigali Heights Ltd"

currency*Currency

ISO 4217, and the currency of every line — an invoice is in one currency.

Length3 <= length <= 3

Example"RWF"

lines*array<>

At least one. An invoice with no lines has no total, so it is refused rather than created as a zero.

Items1 <= items

customer_email?|

Where the invoice and its reminders are sent. Omit it and the invoice is still created — you just deliver it yourself, and reminders have nowhere to go.

Example"accounts@kigaliheights.rw"

due_date?|

YYYY-MM-DD. What reminders are scheduled against and what makes an invoice overdue; without one it stays open indefinitely.

Example"2026-10-15"

notes?|

Shown to the customer — payment terms, a PO number.

Example"Net 30. Quote the invoice number on payment."

Response Body

`application/json`

curl -X POST "https://example.com/api/b/v1/invoices" \  -H "Content-Type: application/json" \  -d '{    "number": "INV-2026-0042",    "customer_name": "Kigali Heights Ltd",    "currency": "RWF",    "lines": [      {        "description": "Consulting — August 2026",        "unit_price_minor": 250000      }    ]  }'

{  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  "number": "string",  "customer_name": "string",  "customer_email": "string",  "currency": "string",  "subtotal_minor": 0,  "tax_minor": 0,  "total_minor": 0,  "paid_minor": 0,  "outstanding_minor": 0,  "state": "draft",  "due_date": "2019-08-24",  "notes": "string",  "sent_at": "2019-08-24T14:15:22Z",  "paid_at": "2019-08-24T14:15:22Z",  "created_at": "2019-08-24T14:15:22Z",  "payment_link_slug": "string",  "lines": [],  "reminders": []}

Authorization

Cookie Parameters

Request Body

Response Body

201application/json

422application/json

`application/json`

`application/json`