Create an invoice

POST

/invoices

Creates a new invoice in draft status for the authenticated entity, billed against one of its active accounts. You supply the line items, any applicable charges (taxes, fees, discounts), and optional payment tranches; the server computes each line item's amount, resolves charge and tranche amounts (percentage or flat), and derives total_amount, total_deductible_charges, and total_additional_charges. The invoice is not sent to the recipient by this call — it only creates the draft record.

If tranches are supplied, the sum of their resolved amounts must exactly equal the computed total_amount, or the request fails with a validation error. entity_id is always taken from the authenticated caller (JWT or secret key) and cannot be overridden in the request body.

Request

Authorization

JWT Bearer

Add the parameter

Authorization

to Headers

Example:

Authorization: ********************

Bearer Token

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

Authorization: Bearer ********************

Body Params application/jsonRequired

Examples

Responses

🟢201

application/json

The invoice was created successfully in draft status, with all charge, line-item, and tranche amounts resolved server-side.

Bodyapplication/json

🟠400

🟠401

🟠404

Request Example

Shell

JavaScript

Java

Swift

cURL

Minimal invoice with required fields onlyInvoice with charges, tranches, and metadata

curl --location '/invoices' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "account_id": "01HXYZ1234567890ABCDEFGHIJ",
    "currency": "NGN",
    "due_date": 1798761600000,
    "recipient": {
        "name": "Jane Doe",
        "email": "jane.doe@example.com"
    },
    "line_items": [
        {
            "name": "UI/UX Design Sprint",
            "unit_amount": 250000,
            "quantity": 2
        }
    ]
}'

Response Example

201 - Success

{
    "message": "Invoice created successfully",
    "status": "success",
    "data": {
        "id": "01HINV9876543210ZYXWVUTSRQ",
        "entity_id": "01HABC9999888877776666ZZZZZ",
        "account_id": "01HXYZ1234567890ABCDEFGHIJ",
        "invoice_number": "INV-01HINV9876543210ZYXWVUTSRQ",
        "currency": "NGN",
        "description": "Consulting services - August 2026",
        "due_date": 1798761600000,
        "status": "draft",
        "issued_at": null,
        "fully_paid_at": null,
        "payment_status": "unpaid",
        "payment_intent_id": null,
        "counterparty_id": "01HCPY7777888899990000CCCC",
        "recipient": {
            "name": "Jane Doe",
            "email": "jane.doe@example.com",
            "mobile": "+2348012345678"
        },
        "line_items": [
            {
                "id": "01HLIN1111222233334444AAAA",
                "name": "UI/UX Design Sprint",
                "description": "Two-week design sprint covering wireframes and prototypes",
                "unit_amount": 250000,
                "quantity": 2,
                "amount": 500000
            }
        ],
        "applicable_charges": [
            {
                "category": "tax",
                "charge_name": "VAT",
                "description": "Value Added Tax at standard rate",
                "value": 7.5,
                "value_type": "percentage",
                "application_type": "additional",
                "resolved_amount": 37500,
                "basis": "subtotal",
                "sequence": 1
            }
        ],
        "tranches": [],
        "client_meta": {
            "order_id": "ord_88abc123"
        },
        "customisation_meta": null,
        "total_amount": 537500,
        "total_deductible_charges": 0,
        "total_additional_charges": 37500,
        "viewed_at": null,
        "last_sent_at": null,
        "created": 1755700000000,
        "updated": 1755700000000
    }
}

Modified at 2026-09-30 00:29:30

Retrieve a published payment page by slug

List invoices