Logo GenukaGenuka Pay
API ReferenceSubscriptions

Overview

Bill your customers on a recurring schedule through mobile money, with WhatsApp and email reminders, from the API.

The Subscriptions module replaces direct debit, which does not exist in mobile money: each due date becomes an invoice, sent to the customer on WhatsApp or by email, followed up with reminders until it is paid, and payable in one click through a mobile money payment request. Genuka Pay suspends and then ends unpaid subscriptions, and notifies you by webhook at every step.

To understand how it works and the steps of an integration, start with the subscriptions guide.

Authentication

Subscription routes use the same keys and the same HMAC signature as the Payments API. See Authentication.

Authenticated Request Headers
X-Public-Key: YOUR_PUBLIC_KEY
X-Timestamp: UNIX_TIMESTAMP
X-Signature: HMAC_SHA256_SIGNATURE

On lists, the signed string contains the path with its query string, exactly as sent: /api/v1/subscriptions?filter[status]=active&per_page=50.

Sandbox and live

The key determines the environment: a sandbox key reads and writes sandbox data, a live key reads and writes live data. Neither environment can see the other: an ID from the other environment returns 404.

  • Sandbox: always available, free. Messages to customers are simulated (no real WhatsApp message or email is sent), payments follow the test numbers, and you can advance time to watch a subscription go through its stages.
  • Live: always available. Without the paid add-on (Starter plan), your account is on the Free plan: at most 50 live subscriptions not yet cancelled or completed, a monthly quota of WhatsApp and SMS messages (100 by default; reminders then go out by email, one-time codes are never held back), no recording of cash payments, and higher fees on each subscriber payment. The limits and your usage show in the dashboard, on the Subscriptions add-on page, and through GET /billing/addon. When a limit refuses a request, the response is 402 with a code:
    • free_plan_subscription_limit on POST /subscriptions (and as a row error of the CSV import): the maximum number of active subscriptions is reached;
    • free_plan_manual_payments on POST /invoices/{invoice}/manual-payments: the Free plan does not record cash payments.

Your company profile must also be complete, in sandbox and live alike. Otherwise: 403 COMPANY_PROFILE_INCOMPLETE.

Idempotency

Every POST route accepts the Idempotency-Key header. Retrying a request with the same key creates nothing new: you get the first response back, with the Idempotent-Replayed: true header.

Idempotency-Key: sub-acct-42-gym
  • The key is scoped to your application (sandbox and live are separate) and kept for 24 hours. 255 characters at most.
  • Reusing a key with a different request (another path or another body) is rejected: 422 idempotency_key_reused.
  • Two concurrent requests with the same key: the second one gets 409 idempotency_request_in_progress.
  • Every response is replayed, validation errors included. After a 422, fix the request and use a new key. 5xx, 409, and 429 responses are not stored: retry with the same key.

Idempotency does not apply to PATCH and DELETE routes.

Formats

  • IDs: 26-character lowercase strings, for example 01k79z2a4b6c8d0e2f4g6h8j0k.
  • Amounts: integers in the minor unit. XAF and XOF have no decimals: 15000 means 15,000 FCFA. Only these two currencies are accepted.
  • Dates: ISO 8601 in UTC, for example 2026-10-09T23:00:00.000000Z.
  • Days: everything counted in days (due dates, trial, grace period, reminders) follows your business's time zone, Africa/Douala by default, configurable in the settings. A period starts at midnight local time: midnight in Douala is written 23:00:00Z on the previous day. Dates you send in YYYY-MM-DD format are read in that time zone.
  • Language: error messages follow the Accept-Language header (fr or en). Validation messages are translated; most business error messages stay in English.

Pagination, filters and sorting

Lists are paginated:

GET /api/v1/subscriptions?filter[status]=past_due,suspended&sort=-created_at&per_page=50&page=2
ParameterDescription
pagePage number, starting at 1
per_pageItems per page, from 1 to 100. 15 by default.
filter[field]Filter. Separate multiple values with commas.
sortSort field, prefix with - for descending order
includeRelated objects to include, on some routes
{
  "data": [ { "id": "01k79z2a4b6c8d0e2f4g6h8j0k", "object": "subscription" } ],
  "links": { "first": "...&page=1", "last": "...&page=2", "prev": "...&page=1", "next": null },
  "meta": { "current_page": 2, "from": 51, "last_page": 2, "per_page": 50, "to": 63, "total": 63 }
}

A filter, sort, or include that the route does not support returns 400.

Errors

Base your logic on the HTTP status code, then on code when it is present, then on errors for a 422. Do not rely on message, which can change.

ShapeExample
Validation422 {"message": "...", "errors": {"price_id": ["..."]}}
Business error422 {"message": "Only an open invoice can be changed; this one is paid.", "code": "invoice_not_open"}
Resource not found404 {"message": "Subscription not found."}
HTTP statuscodeCause
400Filter, sort, or include not allowed
401Missing headers or invalid signature, timestamp more than 5 minutes off, inactive application
402free_plan_subscription_limit, free_plan_manual_paymentsFree plan limit reached (live, without the paid add-on)
403COMPANY_PROFILE_INCOMPLETEIncomplete company profile (missing fields listed in missing_fields)
404Object unknown, from another business, or from the other environment
409idempotency_request_in_progressA request with the same Idempotency-Key is in progress
422idempotency_key_reused, idempotency_key_invalidIdempotency key reused or too long
429Too many requests, with the Retry-After header

Route-specific codes are listed on each route's page.

How is this guide?

Last updated on