Invoices
Track your subscription invoices, collect them by mobile money or in cash, send reminders and adjust due dates.
Genuka Pay issues one invoice per subscription period. You never create an invoice yourself: you read invoices, get them paid and adjust them.
Endpoints
GET /api/v1/invoicesGET /api/v1/invoices/{id}GET /api/v1/invoices/{id}/pdfPOST /api/v1/invoices/{id}/payment-requestsPOST /api/v1/invoices/{id}/manual-paymentsPOST /api/v1/invoices/{id}/remindPOST /api/v1/invoices/{id}/shift-due-datePOST /api/v1/invoices/{id}/void
The invoice object
{
"data": {
"id": "01k7a3m2x8q9w4e5r6t7y8z9v0",
"object": "invoice",
"number": "INV-000042",
"status": "open",
"customer_id": "01k79zz1c2v3b4n5m6p7k8j9h0",
"customer": { "id": "01k79zz1c2v3b4n5m6p7k8j9h0", "name": "Awa Ndiaye" },
"subscription_id": "01k7a3m2a1s2d3f4g5h6j7k8m9",
"period_start": "2026-10-09T23:00:00.000000Z",
"period_end": "2026-11-09T23:00:00.000000Z",
"amount_due": 15000,
"amount_paid": 0,
"credit_applied": 0,
"amount_remaining": 15000,
"currency": "XAF",
"due_at": "2026-10-09T23:00:00.000000Z",
"paid_at": null,
"payment_url": "https://pay.genuka.com/billing/invoices/...",
"pdf_url": "https://pay.genuka.com/billing/invoices/.../pdf",
"created_at": "2026-10-06T08:00:00.000000Z"
}
}| Field | Description |
|---|---|
| number | Gapless number, specific to each application: INV-000001, INV-000002… Sandbox and live are numbered separately. |
| status | open, paid, void or uncollectible. See below. |
| customer | { id, name }, returned by list, retrieve and manual payment, and in webhooks |
| period_start, period_end | Billed period. period_end is the start of the next period. |
| amount_due | Amount of the price when the invoice was issued |
| amount_paid | Amount paid and allocated to this invoice |
| credit_applied | Customer credit used on this invoice |
| amount_remaining | Amount left to pay: amount_due − amount_paid − credit_applied, never negative |
| due_at | Due date, at midnight in your business's local time |
| paid_at | Date of the payment that settled the invoice |
| payment_url | Public payment page to share with the customer, no sign-in required |
| pdf_url | Public PDF of the invoice |
| payments | Payments received, with include=payments (see below) |
Statuses
| Status | Meaning |
|---|---|
open | To be paid |
paid | Settled. Final. |
void | Voided by you, or because the subscription ended. Final. |
uncollectible | Remained unpaid until the subscription ended. Final. |
An invoice is issued 3 days before its due date (1 day for a weekly price). The first invoice of a subscription without a trial is issued when the subscription is created. The customer's credit is applied as soon as the invoice is issued and can settle it on its own.
A payment that arrives on an invoice that is already settled or voided is not lost: it becomes credit for the customer (invoice.updated with context.reason: "duplicate_payment").
Invoice payments
| Field | Description |
|---|---|
| source | push (mobile money payment request), page (paid on the invoice page), manual (cash recorded by you) or credit |
| amount | Amount received, including any overpayment |
| payin_id | Mobile money transaction, for push and page |
| paid_at | Payment date |
| note | Your note. A line is added when part of the amount was turned into credit. |
List and retrieve invoices
GET /api/v1/invoices
GET /api/v1/invoices/{id}| Parameter | Description |
|---|---|
| filter[status] | One or more statuses, for example open |
| filter[customer_id] | A customer's invoices |
| filter[subscription_id] | A subscription's invoices |
| include | payments to include the payments |
| sort | created_at, due_at or amount_due, prefixed with - for descending order. Defaults to -created_at. |
| page, per_page | Pagination (list only) |
Get the PDF
GET /api/v1/invoices/{id}/pdfReturns the link to the PDF, not the file: {"data": {"url": "https://pay.genuka.com/billing/invoices/.../pdf"}}. The link is public and requires no authentication: the token it contains acts as the secret. The PDF is rendered in the customer's language, with your branding, the period details, the payments received and a PAID or VOID stamp.
Request a mobile money payment
POST /api/v1/invoices/{id}/payment-requestsSends the customer a payment request (USSD push) for the amount remaining. The customer approves it on their phone.
| Parameter | Type | Required | Description |
|---|---|---|---|
| phone | string | No | Number in E.164 format. Defaults to the subscription's payment_phone. |
{
"data": {
"status": "started",
"payin_id": "01k7d1e2f3g4h5j6k7m8n9p0q1",
"track_id": "PX-01k7d1e2f3g4h5j6k7m8n9p0q1",
"redirect_url": null,
"message": "Approve the payment of 15,000 XAF on your phone (+237670000001)."
}
}status | HTTP code | Meaning |
|---|---|---|
started | 202 | Request sent, the customer approves it on their phone |
redirect_required | 202 | The operator does not support push (Wave, Orange in Ivory Coast…): send the customer to redirect_url |
already_in_flight | 200 | A payment is already in progress on this invoice, nothing new is started |
failed | 200 | Nothing was started: invoice already paid, no number, number without mobile money… The details are in message. |
message is written to be shown to the customer, in the language of the request. An invoice accepts only one payment at a time: the next request is blocked for up to 3 minutes, or until the payment in progress completes.
The outcome arrives by webhook: invoice.paid (with context.source: "push") followed by the subscription event, or invoice.payment_failed. You can also track the transaction with its track_id on GET /payments/status/{track_id}. The number that paid becomes the subscription's payment_phone, and the customer receives a receipt. The underlying transaction also emits the usual transaction.* webhooks.
In sandbox, use the test numbers to choose the payment outcome.
Record a cash payment
POST /api/v1/invoices/{id}/manual-paymentsFor a payment received outside Genuka Pay, at your counter for example. No money goes through Genuka Pay and no fees are charged.
| Parameter | Type | Required | Description |
|---|---|---|---|
| amount | integer | No | Amount received, in minor units. Defaults to the amount remaining. |
| paid_at | datetime | No | Payment date, defaults to now. Cannot be in the future. |
| note | string | No | 500 characters max |
Not available on the Free plan (live, without the paid add-on): 402 free_plan_manual_payments. In sandbox, it always works.
The payment must settle the invoice: an amount lower than the amount remaining is refused (partial_payment_not_supported). A higher amount settles the invoice and the excess becomes credit for the customer.
201 response: the invoice with its payments. The subscription becomes active (or is renewed, or reactivated). Webhooks: invoice.paid (context.source: "manual"), then the subscription event.
Remind the customer
POST /api/v1/invoices/{id}/remindNo body. Immediately sends the reminder that fits the moment: upcoming invoice, due today, overdue, or subscription suspended. The message goes to the customer's preferred contact, then to the other channels if needed.
{
"data": {
"message_id": "01k7c8d9e0f1g2h3j4k5m6n7p8",
"status": "deferred",
"scheduled_for": "2026-10-21T07:00:00.000000Z"
}
}202when a message is sent, withstatusset toqueued. During quiet hours (9 p.m. – 8 a.m. by default, your business's local time), it isdeferredandscheduled_forgives the send time.200withstatus: "skipped"when the customer has no reachable contact.- One manual reminder per invoice per hour. Beyond that:
429reminder_rate_limited, with aRetry-Afterheader in seconds.
No webhook is emitted. The message appears in the customer timeline.
Postpone the due date
POST /api/v1/invoices/{id}/shift-due-dateA goodwill gesture: pushes back the due date of an open invoice.
| Parameter | Type | Required | Description |
|---|---|---|---|
| due_at | string | Yes | New date YYYY-MM-DD, in your business's local time, later than the current due date |
Reminders and the grace period restart from the new date. A subscription that is late on this invoice gets back what the new date gives it: suspended returns to past_due (access restored) if the new date's grace period is still running, and past_due returns to active if the day after the new date has not come yet. A subscription whose trial ended unpaid stays past_due. Webhooks: invoice.updated (context.reason: "due_date_shifted"), and subscription.updated if the status changes.
Void an invoice
POST /api/v1/invoices/{id}/void| Parameter | Type | Required | Description |
|---|---|---|---|
| replace | boolean | No | Issue a replacement invoice. true by default as long as the subscription still bills this period. |
| due_at | string | No | Due date of the replacement invoice, YYYY-MM-DD, today or later. Defaults to the due date of the voided invoice. |
The invoice becomes void. The credit it had used is returned to the customer, and any money already paid on it becomes credit. With replace, a new invoice is issued for the same period and amount, with a new number and a new payment link. It is returned in meta.replacement.
Without a replacement, the period is never billed again. Webhooks: invoice.voided, then invoice.created for the replacement invoice.
Errors
| HTTP code | Code | Case |
|---|---|---|
402 | free_plan_manual_payments | Cash payment recorded on the Free plan (live, without the paid add-on) |
404 | Unknown invoice, or one from another business or the other environment | |
422 | invoice_not_open | The invoice is no longer open |
422 | partial_payment_not_supported | Manual payment lower than the amount remaining |
422 | payment_in_progress | Reminder sent while a payment is in progress |
422 | due_date_not_later | New due date that is not later than the current one |
422 | invoice_not_replaceable | Replacement requested while the subscription no longer bills this period |
429 | reminder_rate_limited | Manual reminder less than an hour after the previous one |
How is this guide?
Last updated on