Logo GenukaGenuka Pay
API ReferenceSubscriptions

Settings and metrics

Your identity on invoices and the portal, the billing time zone, metrics and subscriber import.

Endpoints

  • GET /api/v1/billing/settings
  • PATCH /api/v1/billing/settings
  • GET /api/v1/billing/metrics
  • POST /api/v1/billing/imports
  • GET /api/v1/billing/imports/{id}
  • POST /api/v1/billing/imports/{id}/commit
  • GET /api/v1/billing/addon
  • POST /api/v1/billing/addon/activate

Settings

GET /api/v1/billing/settings
PATCH /api/v1/billing/settings

Settings are shared between sandbox and live for your business, and remain accessible in live even without the Subscriptions add-on. Until they have been saved once, reading them returns the default values with "id": null.

PATCH accepts any subset of the fields. An empty string clears the field.

FieldDescription
timezoneBilling time zone, for example Africa/Abidjan. Africa/Douala by default. Determines the due day, the time reminders are sent and quiet hours.
default_localefr (default) or en: language of pages and messages when the customer has none
sender_display_nameName shown as the sender of messages, 100 characters max
support_phoneContact number shown to customers, in E.164 format
support_emailReply-to address for emails sent to customers
portal_logo_urlhttps logo shown on the portal, payment pages and invoices. Without one, the company's logo is used. null goes back to the company's logo.
logo_urlRead-only: the logo actually shown (uploaded from the dashboard, portal_logo_url or the company's)
portal_primary_colorPrimary color, #abc or #aabbcc
allow_portal_cancellationSubscribers can cancel from the portal. true by default.
legal_nameLegal business name printed on invoices
legal_identifierLegal identifier (NIU, RCCM…), 100 characters max
legal_addressAddress printed on invoices, 500 characters max

The response also includes, read-only:

  • uses_own_whatsapp_number: reminders are sent from your own WhatsApp number rather than Genuka Pay's shared number. This is set up on request with Genuka; whatsapp_connection_id cannot be changed through the API (422 whatsapp_connection_managed_by_genuka).
  • company_defaults: values taken from your business profile, to prefill a form.

What you cannot configure

The reminder schedule, quiet hours (9 p.m. – 8 a.m.) and invoice numbering (INV-000001) are fixed. The grace period is set per price, with grace_days.

Metrics

GET /api/v1/billing/metrics?from=2026-10-01&to=2026-10-31

from and to are YYYY-MM-DD dates, either both or neither: the current month by default, 366 days max. Metrics cover the application the key belongs to.

FieldDefinition
mrrMonthly recurring revenue, in minor units: sum of active and past_due subscriptions, normalized to a month (a yearly price counts for one twelfth). Current value, independent of the period.
currencyMain currency of the amounts
by_currencyBreakdown { "XAF": { "mrr", "overdue_amount", "active_subscriptions" } } when you bill in several currencies, null otherwise
active_subscriptionsactive and past_due subscriptions (trials excluded)
overdue_amountAmount remaining on open invoices whose due date has passed
cancellationsSubscriptions that ended during the period, excluding those whose first invoice was never paid
renewal_on_time_rateShare of invoices that fell due during the period and were paid on or before their due date
recovery_rateAmong invoices that became overdue, the share paid before suspension
reachable_rateShare of active subscribers with at least one verified, reachable contact
channel_conversionPer channel (whatsapp, sms, email): share of delivered reminders followed by a payment within 24 hours
period{ from, to, timezone }

Rates are decimals between 0 and 1, or null when there is nothing to measure.

Import existing subscribers

To bring over subscribers managed elsewhere, import a CSV file from the dashboard (Subscriptions → Subscribers → Import) or through the API. Either way, you see a row-by-row preview before confirming.

  • Up to 5,000 rows, 5 MB. Comma, semicolon or tab separator. UTF-8 or Windows-1252.
  • Headers are recognized in French or English, ignoring accents and case. Unknown columns are ignored.
ColumnRequiredOther accepted headers
nameYesnom, nom_complet, nom_client, full_name, customer_name
phoneYestelephone, tel, whatsapp, numero, mobile, phone_number
next_due_dateYesprochaine_echeance, echeance, due_date, next_due. Date YYYY-MM-DD, today or later.
price_idYes, unless a default price is chosen at importformule, formule_id, plan, price
emailNomail, courriel, e_mail
external_idNoreference, reference_client, client_id, member_id
beneficiary_nameNobeneficiaire, nom_beneficiaire, eleve, student, beneficiary
beneficiary_referenceNomatricule, reference_beneficiaire, beneficiary_ref
cycles_billedNoecheances_payees, periods_paid, installments_paid

Each valid row creates a customer (or reuses the one that already has that phone number) and an active subscription whose current period ends on next_due_date. The first invoice is issued 3 days before that date. Webhooks: customer.created and subscription.created, with context.source: "import".

Import through the API

  1. Send the file's content as text, in a JSON body signed like any other request:
curl -X POST "https://api-pay.genuka.com/api/v1/billing/imports" \
  -H "X-Public-Key: YOUR_PUBLIC_KEY" \
  -H "X-Timestamp: UNIX_TIMESTAMP" \
  -H "X-Signature: HMAC_SHA256_SIGNATURE" \
  -H "Content-Type: application/json" \
  -d '{
    "csv": "name,phone,next_due_date\nAwa Ndiaye,+237690123456,2026-11-05\n",
    "file_name": "students.csv",
    "price_id": "01k79y8m0n2p4q6r8s0t2v4w6x",
    "consent_attested": true
  }'
ParameterTypeRequiredDescription
csvstringYes, unless file is sentContent of the CSV file, 5 MB max
filefileNoAlternative to csv: the file itself, sent as multipart/form-data (.csv or .txt, 5 MB max). Do not send both.
file_namestringNoName shown for the import
price_idstringNoPrice for rows that do not specify one
consent_attestedbooleanYestrue: you attest that every subscriber agreed to receive your reminders

Response 201: the preview, without creating anything. rows_total, rows_valid, and rows_invalid summarize the file; rows details each row with its errors (code: required, invalid_phone, invalid_date, past_date, unknown_price, duplicate_in_file, already_subscribed, price_unavailable, free_plan_subscription_limit…). A file that cannot be read or is missing a required column returns 422 on csv (or file).

  1. Confirm with POST /api/v1/billing/imports/{id}/commit. Valid rows are created in the background: the 202 response has the status committing; follow progress with GET /api/v1/billing/imports/{id} until it reaches committed (or failed). Rows that became invalid in the meantime are skipped and reported. A second call once the import has finished returns 409 import_already_committed.

Subscriptions add-on

GET /api/v1/billing/addon

Returns your current plan and your usage of the Free plan limits, as shown on the dashboard's Subscriptions add-on page:

{
  "data": {
    "object": "billing_addon",
    "active": false,
    "plan": "free",
    "free_plan_applies": true,
    "free_plan": { "surcharge_rate": 0.02, "max_active_subscriptions": 50, "monthly_messages": 100, "manual_payments": false },
    "usage": { "active_subscriptions": 12, "messages_this_month": 37 },
    "environment": "live",
    "status": null,
    "available_tiers": []
  }
}
FieldDescription
activeThe paid add-on is in effect for the key's environment. Always true in sandbox.
planfree or paid
free_plan_appliesThe Free plan limits apply to this environment (live without the paid add-on)
free_planThe Free plan limits: fee surcharge on each subscription payment, maximum active subscriptions, WhatsApp and SMS messages per calendar month
usageYour live subscriptions not yet cancelled or completed, and the WhatsApp and SMS messages sent this month
status, subscription_id, current_period_end, access_until, cancel_at_period_endYour add-on subscription, null without one
open_invoice, payment_urlAdd-on invoice to pay, if any
available_tiersPaid tiers on sale

POST /api/v1/billing/addon/activate (body: price_id, one of the available_tiers) subscribes you to a paid tier. The add-on is an ordinary subscription billed by Genuka Pay: it takes effect once that subscription grants access (first invoice paid, or during the tier's trial if it has one). Activation is normally done from the dashboard. Errors: 409 subscriptions_addon_exists (another tier is already active), 503 subscriptions_addon_unavailable (not on sale yet). Limit: 10 calls per minute.

How is this guide?

Last updated on