Logo GenukaGenuka Pay
API ReferenceSubscriptions

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/customers
  • POST /api/v1/customers
  • GET /api/v1/customers/{id}
  • PATCH /api/v1/customers/{id}
  • GET /api/v1/customers/{id}/access
  • POST /api/v1/customers/{id}/contacts
  • DELETE /api/v1/customers/{id}/contacts/{contact_id}
  • GET /api/v1/customers/{id}/timeline

Create a customer

POST /api/v1/customers
ParameterTypeRequiredDescription
namestringYesName shown in messages, 255 characters at most
emailstringNoEmail address. Also used as the fallback email destination if the customer has no email contact.
localestringNofr or en: language of the messages sent to the customer. Defaults to the language set in your subscription settings, otherwise fr.
external_idstringNoYour own reference. Unique among the application's customers.
metadataobjectNoFree-form data
consent_atdateNoDate on which the customer agreed to receive messages
consent_sourcestringNosignup_link, import_attested, api, or portal. api by default when consent_at is provided.
contactsarrayNoUp to 10 contacts, see below
contacts[].channelstringYeswhatsapp, sms, or email
contacts[].valuestringYesNumber or address
contacts[].is_preferredbooleanNoContact 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

FieldDescription
idCustomer ID
external_id, name, email, locale, metadataAs stored
contactsThe customer's contacts, preferred one first
subscriptionsSummary of each subscription, newest first: id, status, has_access, access_until, price_id, product_name
credit_balancesThe 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_risktrue 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_atCreation date

consent_at and consent_source are stored but not returned.

The contact object

FieldDescription
channelwhatsapp, sms, or email
valueE.164 number or email address
verifiedtrue when the customer confirmed this contact with a one-time code (customer portal or subscription link). A contact you add is never verified.
reachabilityunknown on creation, reachable after a first successful delivery, unreachable after a permanent error or 3 failures in a row
last_delivered_atLast successful delivery
opted_outtrue when the customer asked to stop receiving messages on this channel (Stop button on WhatsApp, or customer portal)
is_preferredContact 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
ParameterDescription
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
sortcreated_at or name, prefix with - for descending order. -created_at by default.
page, per_pagePagination

Check a customer's access

GET /api/v1/customers/{id}/access

For 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_access is true for the trialing, active, and past_due statuses (the due date has passed but the grace period is still running), and false otherwise. It stays false before the start date of a subscription created to start later, even once paid.
  • access_until is the end of the trial for trialing, and the end of the paid period plus the grace period for active and past_due. No grace period applies when the period is the last one: a scheduled cancellation, or the last period of a fixed-term price. null for 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
ParameterTypeRequiredDescription
channelstringYeswhatsapp, sms, or email
valuestringYesNumber or address, normalized as when creating the customer
is_preferredbooleanNoMakes 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}/timeline

The timeline mixes, newest first:

  • the events of the customer and of its contacts, subscriptions, and invoices (kind: "activity"), with their type (the webhook event name), subject_type, subject_id, and data (previous_attributes, context);
  • the messages sent (kind: "message"), with their channel, template, status (queued, deferred, sent, delivered, read, failed, skipped), the recipient to, 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 statusCause
404Customer or contact unknown, deleted, from another business, or from the other environment
422Invalid field: number not in international format, invalid email, external_id already in use, duplicate contact, several preferred contacts
400Filter or sort not allowed

How is this guide?

Last updated on