Settings and metrics
Your identity on invoices and the portal, the billing time zone, metrics and subscriber import.
Endpoints
GET /api/v1/billing/settingsPATCH /api/v1/billing/settingsGET /api/v1/billing/metricsPOST /api/v1/billing/importsGET /api/v1/billing/imports/{id}POST /api/v1/billing/imports/{id}/commitGET /api/v1/billing/addonPOST /api/v1/billing/addon/activate
Settings
GET /api/v1/billing/settings
PATCH /api/v1/billing/settingsSettings 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.
| Field | Description |
|---|---|
| timezone | Billing time zone, for example Africa/Abidjan. Africa/Douala by default. Determines the due day, the time reminders are sent and quiet hours. |
| default_locale | fr (default) or en: language of pages and messages when the customer has none |
| sender_display_name | Name shown as the sender of messages, 100 characters max |
| support_phone | Contact number shown to customers, in E.164 format |
| support_email | Reply-to address for emails sent to customers |
| portal_logo_url | https 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_url | Read-only: the logo actually shown (uploaded from the dashboard, portal_logo_url or the company's) |
| portal_primary_color | Primary color, #abc or #aabbcc |
| allow_portal_cancellation | Subscribers can cancel from the portal. true by default. |
| legal_name | Legal business name printed on invoices |
| legal_identifier | Legal identifier (NIU, RCCM…), 100 characters max |
| legal_address | Address 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_idcannot be changed through the API (422whatsapp_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-31from 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.
| Field | Definition |
|---|---|
| mrr | Monthly 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. |
| currency | Main currency of the amounts |
| by_currency | Breakdown { "XAF": { "mrr", "overdue_amount", "active_subscriptions" } } when you bill in several currencies, null otherwise |
| active_subscriptions | active and past_due subscriptions (trials excluded) |
| overdue_amount | Amount remaining on open invoices whose due date has passed |
| cancellations | Subscriptions that ended during the period, excluding those whose first invoice was never paid |
| renewal_on_time_rate | Share of invoices that fell due during the period and were paid on or before their due date |
| recovery_rate | Among invoices that became overdue, the share paid before suspension |
| reachable_rate | Share of active subscribers with at least one verified, reachable contact |
| channel_conversion | Per 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.
| Column | Required | Other accepted headers |
|---|---|---|
| name | Yes | nom, nom_complet, nom_client, full_name, customer_name |
| phone | Yes | telephone, tel, whatsapp, numero, mobile, phone_number |
| next_due_date | Yes | prochaine_echeance, echeance, due_date, next_due. Date YYYY-MM-DD, today or later. |
| price_id | Yes, unless a default price is chosen at import | formule, formule_id, plan, price |
| No | mail, courriel, e_mail | |
| external_id | No | reference, reference_client, client_id, member_id |
| beneficiary_name | No | beneficiaire, nom_beneficiaire, eleve, student, beneficiary |
| beneficiary_reference | No | matricule, reference_beneficiaire, beneficiary_ref |
| cycles_billed | No | echeances_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
- 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
}'| Parameter | Type | Required | Description |
|---|---|---|---|
| csv | string | Yes, unless file is sent | Content of the CSV file, 5 MB max |
| file | file | No | Alternative to csv: the file itself, sent as multipart/form-data (.csv or .txt, 5 MB max). Do not send both. |
| file_name | string | No | Name shown for the import |
| price_id | string | No | Price for rows that do not specify one |
| consent_attested | boolean | Yes | true: 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).
- Confirm with
POST /api/v1/billing/imports/{id}/commit. Valid rows are created in the background: the202response has the statuscommitting; follow progress withGET /api/v1/billing/imports/{id}until it reachescommitted(orfailed). Rows that became invalid in the meantime are skipped and reported. A second call once the import has finished returns409import_already_committed.
Subscriptions add-on
GET /api/v1/billing/addonReturns 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": []
}
}| Field | Description |
|---|---|
| active | The paid add-on is in effect for the key's environment. Always true in sandbox. |
| plan | free or paid |
| free_plan_applies | The Free plan limits apply to this environment (live without the paid add-on) |
| free_plan | The Free plan limits: fee surcharge on each subscription payment, maximum active subscriptions, WhatsApp and SMS messages per calendar month |
| usage | Your 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_end | Your add-on subscription, null without one |
| open_invoice, payment_url | Add-on invoice to pay, if any |
| available_tiers | Paid 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