Create and send an invoice

Lifecycle

An invoice moves through these statuses:

draft ──► open ──► sent ──► paid
            └──────────────► paid

Status	Meaning	How it gets there
draft	Work in progress; can’t be sent	Create with "status": "draft"
open	Final and ready to send (the default)	Create normally, or PATCH a draft with "status": "open"
sent	Emailed to the customer	POST /invoices/{id}/send, or PATCH with "status": "sent" if you sent it yourself
paid	Settled	PATCH with "status": "paid"
deleted	Removed	DELETE /invoices/{id}

Other changes are rejected with invalid_status_transition. Deleted invoices can’t be changed, rendered or sent.

Creating an invoice

Only currency, customer.name and at least one line item are required:

{
  "currency": "NGN",
  "customer": { "name": "Bola Ade", "email": "bola@example.com" },
  "line_items": [
    { "description": "Website design", "quantity": 1, "unit_amount": 25000000 },
    { "description": "Hosting (12 months)", "quantity": 12, "unit_amount": 500000 }
  ]
}

Everything else is optional:

Field	Default and notes
number	Next in sequence (INV-001…). If you set your own, it must be unique in your business.
issue_date, due_date	Today (UTC); due date defaults to the issue date. Format YYYY-MM-DD.
tax_percent, discount_percent	0. Percentages of the subtotal, up to two decimals.
issuer	Your business details. Override per invoice if needed.
payment_terms	Free text printed on the invoice, e.g. “Net 30”.
payment_details	An object of bank or payment instructions printed on the invoice.
template	"1" to "4": four invoice designs.
branding	primary_color, secondary_color, font_family, logo_url (https).
external_ref	Your own ID, e.g. your order number. Filter lists by it.
metadata	Up to 50 string key–value pairs for your own use.

Totals are calculated for you, and the response always includes subtotal, tax_amount, discount_amount and total in minor units.

Tip

Set external_ref to your own order or customer ID. You can then find the invoice with GET /invoices?external_ref=order_123 without storing Brrndops IDs.

Updating an invoice

PATCH /invoices/{id} changes only the fields you send:

curl -X PATCH https://api.brrndops.com/v1/invoices/inv_... \
  -H "Authorization: Bearer $BRRNDOPS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "status": "paid", "metadata": { "paid_via": "transfer" } }'

• Sending line_items replaces all line items.
• In metadata, set a key to "" to remove it.
• Changing currency requires sending line_items in the new currency, so amounts are never silently reinterpreted.

Rendering and sending

• GET /invoices/{id}/pdf returns the PDF, rendered with the invoice’s template and branding.
• POST /invoices/{id}/send emails the PDF to customer.email, or to {"to": "…"} if you pass it, and moves an open invoice to sent. Draft invoices must be opened first.

In sandbox, PDFs are watermarked and no email is sent.

Limits

• Up to 500 line items per invoice.
• Request bodies up to 2MB.
• Amounts up to 9,999,999,999 minor units (₦99,999,999.99).