Customer Invoices

The Customer Invoices page (/customer-invoices) is a read-only cross-merchant view of every invoice that merchants in your network have issued to their customers. It surfaces commercial activity across all your merchants in one place — useful for monitoring platform value, auditing receivables risk, and supporting merchants when they have questions about a specific invoice.

When to Use This Page

Need	What to do
See total invoice volume across your merchant network	Open the list — the footer shows the count for the current page.
Find a specific invoice by number	Type the invoice number (e.g. `INV-2026-0001`) into the search field.
Review one merchant’s invoice activity	From the merchant detail page (`/merchants/:id`), the embedded Customer Invoices section shows that merchant’s recent invoices. To see the full filtered view, navigate to `/customer-invoices?business_id=<merchantId>`.
Audit an invoice’s lifecycle	Click any row to open the detail page. The Lifecycle section and Audit Timeline track every state change.

List View

Columns

Column	Description
Invoice #	Merchant-issued invoice number, formatted `INV-YYYY-NNNN`. Monospace font for scanability.
Business	Name of the merchant who issued the invoice.
Customer	Name of the customer the invoice was issued to.
Status	Coloured badge: Draft, Sent, Partial, Paid, Cancelled, Refunded.
Total	Total invoice amount in Naira.
Balance	Remaining unpaid balance. Equals Total for `Sent`, `0` for `Paid`, partial for `Partial`.
Issued	Invoice date (the date the merchant created/sent the invoice).

Click any row to open the invoice detail page.

Filters

Filters narrow the cross-merchant list. Changing any filter resets pagination to the first page.

Filter	Type	Options
Search invoice #	Text input	Partial match on the invoice number. Debounced 300ms; minimum 2 characters before it queries.
Status	Dropdown	All statuses, Draft, Sent, Partially paid, Paid, Cancelled, Refunded.
Kind	Dropdown	All kinds, Invoice, Tax Invoice, Proforma.
From	Date	Issued on or after this date.
To	Date	Issued on or before this date.

Pagination

The list uses cursor-based pagination — the backend does not return a total count because the dataset spans every merchant in your network and counting is expensive at scale. Instead:

The Next button advances using the cursor returned by the current page.
The Previous button walks back through cursors visited so far in this session.
Page size is fixed at 20 invoices per page.

The footer shows Showing N invoice(s) for the current page (no overall total).

Per-Merchant Scope

When you open a merchant’s detail page (/merchants/:id), the Customer Invoices section shows that merchant’s recent invoices in an embedded table — page size 10. The summary line shows status breakdown counts (e.g. DRAFT · 1 SENT · 1 PARTIALLY_PAID · 1 PAID · 1) and the Naira volume on the page. Each row is clickable and opens the cross-merchant detail page.

For a fully-filtered cross-merchant view scoped to a single merchant, navigate to:

/customer-invoices?business_id=<merchantId>

This pre-applies the business_id filter so other filters (status, kind, date range) compose on top.

Detail View

Clicking any invoice — from the cross-merchant list or from a merchant’s embedded section — opens the detail page (/customer-invoices/:id).

The header shows the invoice number, status badge, and kind label (Invoice / Tax Invoice / Proforma). Subtitle: “Read-only partner view · No actions”.

Business

Field	Source
Name	`businesses.name`
Business ID	UUID (clickable to copy)
Created by	`users.name` of the merchant staff who created the invoice

Customer

Field	Source
Name	`customers.name`
Customer ID	UUID

Financials

Subtotal, Total, Amount paid, and Balance. Tax and discount fields render only when nonzero.

Lifecycle

Timestamps for the invoice’s state transitions:

Field	Description
Issued	Invoice date (merchant-set)
Due	Due date for payment
Shared	When the merchant shared the invoice with the customer (if shared)
Paid	When the invoice was fully paid (if paid)
Created	When the invoice record was first created

Line Items

Each line shows: Product, Qty, Unit Price, Total.

Payments

Each payment recorded against the invoice shows: Method (cash, POS, transfer, etc.), Amount, Reference (provider reference or merchant-entered note), Received (timestamp).

When the invoice has no payments, a “No payments recorded.” empty state appears.

Audit Timeline

The bottom of the page lists audit events for this invoice — each entry shows the action (e.g. CUSTOMER_INVOICE_CREATED, CUSTOMER_INVOICE_SHARED, CUSTOMER_INVOICE_MARKED_PAID), the actor (merchant user email), the timestamp, and an optional reason.

When the invoice has no audit history yet, an “No audit events recorded yet.” empty state appears.

Read-Only Boundary

Partners are intentionally read-only on customer invoice data. The portal cannot:

Create, edit, or void a merchant’s invoice.
Mark an invoice as paid.
Send the invoice to a customer.
Issue a refund.

Those actions belong to the merchant. If you need a change made to an invoice, contact the merchant directly through the channels you maintain with them.

Common Tasks

Audit a single invoice end-to-end

Search for the invoice number in the list.
Click the row to open the detail page.
Scroll to the Lifecycle card to see when the invoice transitioned states.
Scroll to the Audit Timeline at the bottom for the full per-action history (actor, timestamp, optional reason).

Find every overdue invoice across your network

Set Status to Sent (sent but not yet paid).
Set To to today’s date minus your overdue threshold (e.g. 30 days ago).
Page through the results to identify outstanding balances.

Drill from a single merchant into their invoices

Open /merchants and search for the merchant.
Click the merchant row to open their detail page.
The Customer Invoices section near the bottom shows up to 10 recent invoices for that merchant.
Click any row to open the cross-merchant detail page; or visit /customer-invoices?business_id=<merchantId> for a filtered cross-merchant list.