Bills are supplier invoices you owe. Unlike expenses (immediate cash out), bills sit in accounts payable until paid — often in instalments. Each payment posts its own GL entry, with WHT handled at payment time.

List bills

GET/v1/bills

Returns bills for a business, newest first.

Query parameters

Field	Type	Required	Notes
`businessId`	string	yes
`limit`	integer	no	Default 50, max 100.
`status`	string	no	`draft`, `unpaid`, `partial`, `paid`, `overdue`, `voided`.
`supplierId`	string	no

Get a single bill

GET/v1/bills/{id}

Fetches one bill. Supplier PII is decrypted in the response.

Create a bill

POST/v1/bills

Records a supplier bill in accounts payable.

Body

Field	Type	Required	Notes
`supplierId`	string	yes	Must be an active supplier.
`billDate`	ISO 8601	yes	Bill issue date.
`dueDate`	ISO 8601	yes	Payment due date.
`lineItems`	array	yes	1–100 items with `description`, `quantity`, `unitPrice`, `accountId`.
`vatRate`	number	no	Defaults to 7.5.
`notes`	string	no
`reference`	string	no	Supplier's bill number.

Response — 201

{
  "success": true,
  "data": {
    "id": "bill_abc",
    "number": "BILL-2026-003",
    "totalKobo": 10750000,
    "total": 107500,
    "amountPaidKobo": 0,
    "amountDueKobo": 10750000,
    "status": "unpaid",
    "createdAt": "2026-04-17T10:30:00.000Z"
  }
}

Update a bill

PUT/v1/bills/{id}

Edits an unpaid bill. Paid and voided bills are immutable.

Void a bill

POST/v1/bills/{id}/void

Cancels an unpaid bill and reverses its GL entry.

Body

Field	Type	Required	Notes
`reason`	string	yes	Shown in the audit trail.

Record a payment against a bill

POST/v1/bills/{id}/payments

Applies a payment. WHT is computed and transferred to the payable account automatically.

Body

Field	Type	Required	Notes
`amount`	number	yes	Naira amount of this payment (not total bill).
`paymentDate`	ISO 8601	no	Defaults to today.
`paymentMethod`	string	no	`cash`, `bank_transfer`, `card`, `mobile_money`, `cheque`.
`whtRate`	number	no	WHT percentage to withhold on this payment.
`reference`	string	no	Bank transaction ID or cheque number.
`notes`	string	no

The bill's status advances to partial or paid based on the running total. When whtRate > 0, a transfer JE moves the WHT from provision (2022) to payable (2027).

List payments for a bill

GET/v1/bills/{id}/payments

Returns all payments applied to this bill.

Related endpoints

Suppliers
Expenses — for one-off purchases paid immediately
Journal Entries

Bills & Payments

List bills

Query parameters

Get a single bill

Create a bill

Body

Response — 201

Update a bill

Void a bill

Body

Record a payment against a bill

Body

List payments for a bill

Related endpoints