List invoices

GET

/invoices

Returns a paginated list of invoices belonging to the authenticated entity, ordered newest first. Use the optional query parameters to filter by status, payment_status, or account_id. Pagination is cursor-based: each response includes a meta.pagination.cursor value that you pass as the cursor query parameter on the next request to fetch the following page. When meta.pagination.has_more is false, you have reached the end of the list.

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 ********************

Query Params

Responses

🟢200

application/json

Invoices retrieved successfully. Returns a page of invoices and pagination metadata.

Bodyapplication/json

🟠400

🟠401

Request Example

Shell

JavaScript

Java

Swift

curl --location '/invoices?status=issued&statuses=issued%2Csent&search=jane.doe&payment_status=unpaid&account_id=01HQZR2BKPFQ8MXJVT3G7LWNA&created_from=1750000000000&created_to=1760000000000&include_total=true&cursor=01HQZR2BKPFQ8MXJVT3G7LWNE&limit=20' \
--header 'Authorization: Bearer <token>'

Response Example

200 - First page — more results available

{
    "message": "Invoices retrieved successfully",
    "status": "success",
    "data": [
        {
            "id": "01HQZR2BKPFQ8MXJVT3G7LWNZ",
            "entity_id": "01HQZR2BKPFQ8MXJVT3G7LWNA",
            "account_id": "01HQZR2BKPFQ8MXJVT3G7LWNB",
            "invoice_number": "INV-01HQZR2BKPFQ8MXJVT3G7LWNZ",
            "currency": "NGN",
            "description": "Consulting services for Q3 2026",
            "due_date": 1786060800000,
            "status": "issued",
            "issued_at": 1755000000000,
            "fully_paid_at": null,
            "payment_status": "unpaid",
            "payment_intent_id": null,
            "counterparty_id": null,
            "recipient": {
                "name": "Jane Doe",
                "email": "jane.doe@example.com",
                "mobile": "+2348012345678",
                "address": {
                    "line_one": "12 Adeola Odeku Street",
                    "line_two": "Suite 4B",
                    "city": "Lagos",
                    "state": "Lagos",
                    "country": "Nigeria",
                    "code": "106104",
                    "code_type": "postal"
                }
            },
            "line_items": [
                {
                    "id": "01HQZR2BKPFQ8MXJVT3G7LWN1",
                    "name": "Consulting hours",
                    "description": "40 hours at senior rate",
                    "unit_amount": 5000,
                    "quantity": 40,
                    "amount": 200000
                }
            ],
            "applicable_charges": [
                {
                    "category": "tax",
                    "charge_name": "VAT",
                    "description": "7.5% value added tax",
                    "value": 7.5,
                    "value_type": "percentage",
                    "application_type": "deductible",
                    "resolved_amount": 15000,
                    "basis": "subtotal",
                    "sequence": 1
                }
            ],
            "tranches": [],
            "client_meta": {
                "project_code": "PRJ-2026-014"
            },
            "customisation_meta": null,
            "total_amount": 185000,
            "total_deductible_charges": 15000,
            "total_additional_charges": 0,
            "viewed_at": null,
            "last_sent_at": 1754600000000,
            "created": 1754524800000,
            "updated": 1754524800000
        }
    ],
    "meta": {
        "pagination": {
            "cursor": "01HQZR2BKPFQ8MXJVT3G7LWNZ",
            "has_more": true,
            "total": null
        }
    }
}

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

Create an invoice

Retrieve an invoice