Retrieve a public invoice by invoice number

GET

/public-invoices/{code}

Fetches an invoice by its invoice_number for display on a public, unauthenticated invoice page (e.g. a hosted payment link shared with the invoice recipient). Only invoices in the issued or sent status are visible through this endpoint — invoices that are still a draft, or that have been voided or cancelled, are treated as not found so their existence and contents are never exposed to the public. Each successful call also marks the invoice as viewed for the first time (setting viewed_at), which downstream analytics and reminder logic rely on; subsequent views of the same invoice do not update viewed_at again. The response embeds a minimal entity object (name and logo) so the invoice page can be branded without a separate authenticated lookup.

Request

Path Params

Responses

🟢200

application/json

Invoice found, publicly visible, and returned successfully.

Bodyapplication/json

🟠400

🟠404

Response Example

200 - Success

{
    "message": "Invoice retrieved successfully",
    "status": "success",
    "data": {
        "id": "01HQZR2BKPFQ8MXJVT3G7LWNE",
        "invoice_number": "INV-01HQZR2BKPFQ8MXJVT3G7LWND",
        "currency": "NGN",
        "description": "Consulting services for Q3 2026",
        "due_date": 1767225600000,
        "status": "sent",
        "issued_at": 1754524800000,
        "fully_paid_at": null,
        "payment_status": "unpaid",
        "payment_intent_id": null,
        "recipient": {
            "name": "Ada Lovelace",
            "email": "ada@example.com",
            "mobile": "+2348012345678",
            "address": {
                "line_one": "12 Marina Road",
                "line_two": "Suite 4B",
                "city": "Lagos",
                "state": "Lagos State",
                "country": "Nigeria",
                "code": "101233",
                "code_type": "postal"
            }
        },
        "line_items": [
            {
                "id": "01HQZR2BKPFQ8MXJVT3G7LW01",
                "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% VAT on services",
                "value": 7.5,
                "value_type": "percentage",
                "application_type": "additional",
                "resolved_amount": 15000,
                "basis": "subtotal",
                "sequence": 1
            }
        ],
        "tranches": [
            {
                "id": "01HQZR2BKPFQ8MXJVT3G7LW02",
                "name": "First installment",
                "description": "50% deposit",
                "value": 50,
                "value_type": "percentage",
                "due_date": 1760227200000,
                "resolved_amount": 107500,
                "status": "pending"
            }
        ],
        "client_meta": {
            "external_reference": "ord-2026-0912"
        },
        "customisation_meta": {
            "accent_color": "#1A73E8"
        },
        "total_amount": 215000,
        "total_deductible_charges": 0,
        "total_additional_charges": 15000,
        "created": 1754524800000,
        "updated": 1754524800000,
        "entity": {
            "name": "Acme Exports Ltd",
            "logo": "https://cdn.example.com/entities/acme/logo.png"
        }
    }
}

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

Download a public invoice as a PDF

Send a reminder for an invoice