Customers
Register your subscribers and their reminder contacts, and check at any time what they have access to.
A customer (customer) is the person who pays for your subscriptions. A customer has contacts (WhatsApp, SMS, email) to which Genuka Pay sends invoices, reminders, and receipts.
Endpoints
GET /api/v1/customersPOST /api/v1/customersGET /api/v1/customers/{id}PATCH /api/v1/customers/{id}GET /api/v1/customers/{id}/accessPOST /api/v1/customers/{id}/contactsDELETE /api/v1/customers/{id}/contacts/{contact_id}GET /api/v1/customers/{id}/timeline
Create a customer
POST /api/v1/customers| Parameter | Type | Required | Description |
|---|---|---|---|
| name | string | Yes | Name shown in messages, 255 characters at most |
| string | No | Email address. Also used as the fallback email destination if the customer has no email contact. | |
| locale | string | No | fr or en: language of the messages sent to the customer. Defaults to the language set in your subscription settings, otherwise fr. |
| external_id | string | No | Your own reference. Unique among the application's customers. |
| metadata | object | No | Free-form data |
| consent_at | date | No | Date on which the customer agreed to receive messages |
| consent_source | string | No | signup_link, import_attested, api, or portal. api by default when consent_at is provided. |
| contacts | array | No | Up to 10 contacts, see below |
| contacts[].channel | string | Yes | whatsapp, sms, or email |
| contacts[].value | string | Yes | Number or address |
| contacts[].is_preferred | boolean | No | Contact tried first. Only one preferred contact per customer. |
Phone number format. WhatsApp and SMS numbers are stored in E.164 format (+237690123456). Common notations are accepted and normalized: +237 690 12 34 56, 00237690123456, 237690123456. A national number without a country code (690123456) gets your business's country code. Emails are lowercased.
curl -X POST "https://api-pay.genuka.com/api/v1/customers" \
-H "X-Public-Key: YOUR_PUBLIC_KEY" \
-H "X-Timestamp: UNIX_TIMESTAMP" \
-H "X-Signature: HMAC_SHA256_SIGNATURE" \
-H "Idempotency-Key: customer-acct-42" \
-H "Content-Type: application/json" \
-d '{
"name": "Boulangerie Ndiaye",
"email": "compta@boulangerie.example",
"external_id": "acct_42",
"contacts": [
{ "channel": "whatsapp", "value": "+237 690 12 34 56", "is_preferred": true },
{ "channel": "email", "value": "compta@boulangerie.example" }
]
}'Response 201: the full customer object.
{
"data": {
"id": "01k79z1e8s0t2v4w6x8y0z2a4b",
"object": "customer",
"external_id": "acct_42",
"name": "Boulangerie Ndiaye",
"email": "compta@boulangerie.example",
"locale": "fr",
"metadata": null,
"contacts": [
{
"id": "01k79z1e9a2b4c6d8e0f2g4h6j",
"object": "customer_contact",
"customer_id": "01k79z1e8s0t2v4w6x8y0z2a4b",
"channel": "whatsapp",
"value": "+237690123456",
"verified": false,
"verified_at": null,
"reachability": "unknown",
"last_delivered_at": null,
"opted_out": false,
"is_preferred": true
}
],
"subscriptions": [],
"credit_balances": [],
"at_risk": false,
"created_at": "2026-10-10T08:12:44.000000Z"
}
}The customer object
| Field | Description |
|---|---|
| id | Customer ID |
| external_id, name, email, locale, metadata | As stored |
| contacts | The customer's contacts, preferred one first |
| subscriptions | Summary of each subscription, newest first: id, status, has_access, access_until, price_id, product_name |
| credit_balances | The customer's credit per currency, for example [{"currency": "XAF", "amount": 3000}]. Credit comes from overpayments and is automatically applied to the next invoices. Present on retrieve, create, and update, absent from the list. |
| at_risk | true when no contact can be reached anymore: all opted out or unreachable, or no contact at all. The customer will not receive their reminders. |
| created_at | Creation date |
consent_at and consent_source are stored but not returned.
The contact object
| Field | Description |
|---|---|
| channel | whatsapp, sms, or email |
| value | E.164 number or email address |
| verified | true when the customer confirmed this contact with a one-time code (customer portal or subscription link). A contact you add is never verified. |
| reachability | unknown on creation, reachable after a first successful delivery, unreachable after a permanent error or 3 failures in a row |
| last_delivered_at | Last successful delivery |
| opted_out | true when the customer asked to stop receiving messages on this channel (Stop button on WhatsApp, or customer portal) |
| is_preferred | Contact tried first |
Retrieve and update a customer
GET /api/v1/customers/{id}
PATCH /api/v1/customers/{id}PATCH accepts name, email, locale, external_id, metadata, consent_at, and consent_source. Only the fields you send change. metadata is replaced, not merged. Contacts cannot be changed here: use the contact routes.
A PATCH that changes at least one field emits customer.updated.
List customers
GET /api/v1/customers| Parameter | Description |
|---|---|
| filter[search] | Searches the name, email, external_id, and contacts. A number is found however it is written: +237 6 90…, 00237…, 0690123456. |
| filter[subscription_status] | Customers with at least one subscription in one of these statuses, for example past_due,suspended |
| filter[price_id] | Customers subscribed to one of these prices |
| filter[at_risk] | true: unreachable customers only |
| sort | created_at or name, prefix with - for descending order. -created_at by default. |
| page, per_page | Pagination |
Check a customer's access
GET /api/v1/customers/{id}/accessFor each of the customer's subscriptions, tells you whether it grants access to your service right now, and until when. This is the route to call to grant or revoke access in your application.
{
"data": [
{
"subscription_id": "01k7c0a2b4c6d8e0f2g4h6j8k1",
"status": "past_due",
"has_access": true,
"access_until": "2026-11-16T23:00:00.000000Z",
"product_name": "Gym, unlimited access",
"beneficiary_name": null
}
]
}has_accessistruefor thetrialing,active, andpast_duestatuses (the due date has passed but the grace period is still running), andfalseotherwise. It staysfalsebefore the start date of a subscription created to start later, even once paid.access_untilis the end of the trial fortrialing, and the end of the paid period plus the grace period foractiveandpast_due. No grace period applies when the period is the last one: a scheduled cancellation, or the last period of a fixed-term price.nullfor other statuses.- The list is not paginated and includes every subscription, ended ones included. A customer without subscriptions returns
{"data": []}.
Cache access on your side
Rather than calling this route on every request from your users, store access on your side and update it when you receive subscription webhooks (subscription.activated, .renewed, .past_due, .suspended, .reactivated, .cancelled, .completed, and .updated with context.reason: "started"). Statuses change no later than 15 minutes after midnight, your business's local time.
Manage contacts
Add a contact
POST /api/v1/customers/{id}/contacts| Parameter | Type | Required | Description |
|---|---|---|---|
| channel | string | Yes | whatsapp, sms, or email |
| value | string | Yes | Number or address, normalized as when creating the customer |
| is_preferred | boolean | No | Makes this contact the preferred one and removes that status from the others |
Response 201: the contact object. The same contact cannot be added twice to the same customer, however it is written (422). Adding a contact emits customer.updated on the customer.
Delete a contact
DELETE /api/v1/customers/{id}/contacts/{contact_id}Response 200: {"message": "Contact removed."}. Messages already sent stay in the timeline. Deleting a contact emits customer.updated.
Keep at least one reachable contact
The API lets you delete a customer's last contact. The customer then becomes at_risk and no longer receives any reminders.
How messages are routed
For each message, Genuka Pay first tries the preferred contact, then one contact per channel in the order WhatsApp → SMS → email, starting with contacts already reached successfully. If a message fails, or is not delivered within 2 hours (6 hours for a reminder sent before the due date), it is resent on the next channel. An opted-out (opted_out) or unreachable contact is no longer used. The customer's email address serves as an email contact if they have none.
SMS
SMS sending is not available yet: you can store SMS contacts, but for now messages go from WhatsApp straight to email.
When a customer gets their first subscription, a welcome message is sent to each of their contacts that are still unknown. Its delivery marks the contact reachable. In sandbox, no real message is sent: delivery is simulated.
Customer timeline
GET /api/v1/customers/{id}/timelineThe timeline mixes, newest first:
- the events of the customer and of its contacts, subscriptions, and invoices (
kind: "activity"), with theirtype(the webhook event name),subject_type,subject_id, anddata(previous_attributes,context); - the messages sent (
kind: "message"), with theirchannel,template,status(queued,deferred,sent,delivered,read,failed,skipped), the recipientto, and the sent, delivered, and read dates.
Each entry also has an occurred_at date. Paginated with page and per_page (15 by default, 100 at most).
Errors
| HTTP status | Cause |
|---|---|
404 | Customer or contact unknown, deleted, from another business, or from the other environment |
422 | Invalid field: number not in international format, invalid email, external_id already in use, duplicate contact, several preferred contacts |
400 | Filter or sort not allowed |
How is this guide?
Last updated on