Logo GenukaGenuka Pay
API ReferenceSubscriptions

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/invoices
  • GET /api/v1/invoices/{id}
  • GET /api/v1/invoices/{id}/pdf
  • POST /api/v1/invoices/{id}/payment-requests
  • POST /api/v1/invoices/{id}/manual-payments
  • POST /api/v1/invoices/{id}/remind
  • POST /api/v1/invoices/{id}/shift-due-date
  • POST /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"
  }
}
FieldDescription
numberGapless number, specific to each application: INV-000001, INV-000002… Sandbox and live are numbered separately.
statusopen, paid, void or uncollectible. See below.
customer{ id, name }, returned by list, retrieve and manual payment, and in webhooks
period_start, period_endBilled period. period_end is the start of the next period.
amount_dueAmount of the price when the invoice was issued
amount_paidAmount paid and allocated to this invoice
credit_appliedCustomer credit used on this invoice
amount_remainingAmount left to pay: amount_due − amount_paid − credit_applied, never negative
due_atDue date, at midnight in your business's local time
paid_atDate of the payment that settled the invoice
payment_urlPublic payment page to share with the customer, no sign-in required
pdf_urlPublic PDF of the invoice
paymentsPayments received, with include=payments (see below)

Statuses

StatusMeaning
openTo be paid
paidSettled. Final.
voidVoided by you, or because the subscription ended. Final.
uncollectibleRemained 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

FieldDescription
sourcepush (mobile money payment request), page (paid on the invoice page), manual (cash recorded by you) or credit
amountAmount received, including any overpayment
payin_idMobile money transaction, for push and page
paid_atPayment date
noteYour 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}
ParameterDescription
filter[status]One or more statuses, for example open
filter[customer_id]A customer's invoices
filter[subscription_id]A subscription's invoices
includepayments to include the payments
sortcreated_at, due_at or amount_due, prefixed with - for descending order. Defaults to -created_at.
page, per_pagePagination (list only)

Get the PDF

GET /api/v1/invoices/{id}/pdf

Returns 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-requests

Sends the customer a payment request (USSD push) for the amount remaining. The customer approves it on their phone.

ParameterTypeRequiredDescription
phonestringNoNumber 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)."
  }
}
statusHTTP codeMeaning
started202Request sent, the customer approves it on their phone
redirect_required202The operator does not support push (Wave, Orange in Ivory Coast…): send the customer to redirect_url
already_in_flight200A payment is already in progress on this invoice, nothing new is started
failed200Nothing 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-payments

For a payment received outside Genuka Pay, at your counter for example. No money goes through Genuka Pay and no fees are charged.

ParameterTypeRequiredDescription
amountintegerNoAmount received, in minor units. Defaults to the amount remaining.
paid_atdatetimeNoPayment date, defaults to now. Cannot be in the future.
notestringNo500 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}/remind

No 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"
  }
}
  • 202 when a message is sent, with status set to queued. During quiet hours (9 p.m. – 8 a.m. by default, your business's local time), it is deferred and scheduled_for gives the send time.
  • 200 with status: "skipped" when the customer has no reachable contact.
  • One manual reminder per invoice per hour. Beyond that: 429 reminder_rate_limited, with a Retry-After header in seconds.

No webhook is emitted. The message appears in the customer timeline.

Postpone the due date

POST /api/v1/invoices/{id}/shift-due-date

A goodwill gesture: pushes back the due date of an open invoice.

ParameterTypeRequiredDescription
due_atstringYesNew 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
ParameterTypeRequiredDescription
replacebooleanNoIssue a replacement invoice. true by default as long as the subscription still bills this period.
due_atstringNoDue 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 codeCodeCase
402free_plan_manual_paymentsCash payment recorded on the Free plan (live, without the paid add-on)
404Unknown invoice, or one from another business or the other environment
422invoice_not_openThe invoice is no longer open
422partial_payment_not_supportedManual payment lower than the amount remaining
422payment_in_progressReminder sent while a payment is in progress
422due_date_not_laterNew due date that is not later than the current one
422invoice_not_replaceableReplacement requested while the subscription no longer bills this period
429reminder_rate_limitedManual reminder less than an hour after the previous one

How is this guide?

Last updated on