API reference
Customers
Create, list, update and delete the people who subscribe.
Create, list, retrieve, update and delete the customers you bill. You create a customer, then start a subscription for them.
To link a customer to a user in your own app, put your user's ID in the customer's metadata, or store the customer's id next to your user. Don't match customers to your users by email. A customer can change their email in the customer portal, and two people can share one.
The customer object
Attributes
idstringUnique identifier for the customer.app_idstringThe app the customer belongs to.namestringnullableThe customer's name.phone_numberstringnullableThe customer's phone number. Mobile money payment requests go to this number. Checkout asks for it on the payment step, so a customer who came through checkout hasnulluntil they pay. Their first successful payment saves the number that paid and sends acustomer.updatedevent.emailstringThe customer's email address. Abuna sends every message for the customer to this address.metadataobjectYour own keys and values, like your user's ID.{}when there are none. Events about the customer carry it. The limits are the same as for subscription metadata.languagestringnullableThe language the customer reads their emails, Telegram messages, payment pages, and customer portal in:froren. The customer can change it on those pages.nulluntil you or the customer set it: their pages then follow their browser's language, and everything else is in French.updatesobjectWhere the customer's messages and payment reminders go. Email always goes out, and a chat app comes on top of it. Abuna never shows a chat ID or a phone number here.Show child attributesHide child attributes
channelstringnullableThe chat app the customer chose:whatsapp,telegram, ornullfor email only.emailobjectHas astatus, alwaysactive.telegramobjectHas astatusand aconnected_at.connected_atis the time Telegram was turned on, in Unix seconds, andnullunless the status isactive. The status is one ofoff(not chosen, or turned off),pending(chosen, waiting for the customer to turn it on in Telegram),active(on, so messages go to Telegram too), orstopped(the customer stopped it from Telegram, so messages go by email only until they turn it on again). It also hasconnect_url. While the status ispending, a link that turns Telegram on when the customer opens it and taps Start, for a Turn on reminders button in your app.nullin every other status.whatsappobjectHas astatus, aconnected_at, and aconnect_url, liketelegram.connected_atis the time the customer confirmed WhatsApp, in Unix seconds, andnullunless the status isactive. The status is one ofoff(not chosen, or turned off),active(on, so messages go to WhatsApp too),stopped(the customer sentstopin the chat, so messages go by email only until they confirm their number again), orfailed(the number can't get WhatsApp messages, so messages go by email only until the customer gives another number). WhatsApp is neverpending. The customer confirms their number with a code when they choose it, so it isactiveas soon as they confirm it, andconnect_urlis alwaysnull.
created_attimestampWhen the customer was created, in Unix seconds.
{
"id": "Cu5tM8rA",
"app_id": "8ddhXCDW",
"name": "Jane Doe",
"phone_number": "+237671234567",
"email": "jane@example.com",
"metadata": {
"user_id": "42"
},
"language": "fr",
"created_at": 1727600000,
"updates": {
"channel": "telegram",
"email": {
"status": "active"
},
"telegram": {
"status": "active",
"connected_at": 1727600300,
"connect_url": null
},
"whatsapp": {
"status": "off",
"connected_at": null,
"connect_url": null
}
}
}Create a customer
POST/v1/apps/{appID}/customers
Accepts an Idempotency-Key header.
Creates a customer.
Parameters
emailstringrequiredThe customer's email address.phone_numberstringrequiredThe customer's phone number, with its country code, like+237671234567.namestringThe customer's name.metadataobjectYour own keys and values, like your user's ID. See Metadata for the limits.languagestringfroren: the language of the customer's emails, Telegram messages, and pages. Leave it out if you don't know it.
Returns the customer with status 201. A missing email or phone number returns 422 with code invalid, and so do metadata past its limits and any language other than fr or en. An unknown field returns 400 with code invalid_json.
curl https://api.abuna.app/v1/apps/8ddhXCDW/customers \
-H "Authorization: Bearer sk_test_..." \
-H "Content-Type: application/json" \
-d '{
"name": "Jane Doe",
"email": "jane@example.com",
"phone_number": "+237671234567",
"metadata": {"user_id": "42"},
"language": "fr"
}'{
"id": "Cu5tM8rA",
"app_id": "8ddhXCDW",
"name": "Jane Doe",
"phone_number": "+237671234567",
"email": "jane@example.com",
"metadata": {
"user_id": "42"
},
"language": "fr",
"created_at": 1727600000,
"updates": {
"channel": "telegram",
"email": {
"status": "active"
},
"telegram": {
"status": "active",
"connected_at": 1727600300,
"connect_url": null
},
"whatsapp": {
"status": "off",
"connected_at": null,
"connect_url": null
}
}
}List customers
GET/v1/apps/{appID}/customers
Lists the app's customers, newest first, one page at a time. Each one has two more fields than the customer object.
Query parameters
searchstringReturns only customers whose name or email contains this text. Case doesn't matter. A search that looks like a phone number, digits with an optional+, spaces, dashes, dots, or brackets, also matches phone numbers on the digits alone:671 23 45finds+237671234567.limitintegerHow many customers to return, from 1 to 100. Defaults to 50.cursorstringThenext_cursorfrom the previous page. Send the same filters with it.
Extra attributes
telegram_connectedbooleanWhether the customer gets their messages on Telegram too.active_subscriptionsintegerHow many of the customer's subscriptions areactiveorpast_due(unpaid).
Returns items and next_cursor, as described in Lists and filters. A value that isn't allowed, like a limit above 100, returns 422 with code invalid and the parameter's name in errors.
curl "https://api.abuna.app/v1/apps/8ddhXCDW/customers?search=ana" \
-H "Authorization: Bearer sk_test_..."{
"items": [
{
"id": "Cu5tM8rA",
"app_id": "8ddhXCDW",
"name": "Jane Doe",
"phone_number": "+237671234567",
"email": "jane@example.com",
"metadata": {
"user_id": "42"
},
"language": "fr",
"created_at": 1727600000,
"updates": {
"channel": null,
"email": {
"status": "active"
},
"telegram": {
"status": "off",
"connected_at": null,
"connect_url": null
},
"whatsapp": {
"status": "off",
"connected_at": null,
"connect_url": null
}
},
"telegram_connected": false,
"active_subscriptions": 1
}
],
"next_cursor": null
}Retrieve a customer
GET/v1/apps/{appID}/customers/{id}
Retrieves a customer.
Returns the customer. If the app has no customer with that ID, returns 404 with code not_found.
curl https://api.abuna.app/v1/apps/8ddhXCDW/customers/Cu5tM8rA \
-H "Authorization: Bearer sk_test_..."{
"id": "Cu5tM8rA",
"app_id": "8ddhXCDW",
"name": "Jane Doe",
"phone_number": "+237671234567",
"email": "jane@example.com",
"metadata": {
"user_id": "42"
},
"language": "fr",
"created_at": 1727600000,
"updates": {
"channel": "telegram",
"email": {
"status": "active"
},
"telegram": {
"status": "active",
"connected_at": 1727600300,
"connect_url": null
},
"whatsapp": {
"status": "off",
"connected_at": null,
"connect_url": null
}
}
}Update a customer
PATCH/v1/apps/{appID}/customers/{id}
Updates the fields you send and leaves the rest as they are. If the name, email, phone number, or metadata changed, Abuna records a customer.updated event.
Parameters
namestringThe customer's name. Sendnullto clear it.emailstringThe customer's email address. It can't benull.phone_numberstringThe customer's phone number, with its country code. Abuna saves it as+and digits, so00237 671-234-567becomes+237671234567. It can't benull.metadataobjectReplaces the customer's metadata with the object you send.languagestringfroren. Sendnullto clear it, so the customer's pages follow their browser and everything else is in French.
Returns the customer. An invalid field or an unknown field returns 422 with code invalid. A name, email, phone_number, or language that isn't a string or null returns 400 with code invalid_json and an errors item for the field. If the app has no customer with that ID, returns 404 with code not_found.
curl https://api.abuna.app/v1/apps/8ddhXCDW/customers/Cu5tM8rA \
-H "Authorization: Bearer sk_test_..." \
-H "Content-Type: application/json" \
-X PATCH \
-d '{
"email": "jane.doe@example.com"
}'{
"id": "Cu5tM8rA",
"app_id": "8ddhXCDW",
"name": "Jane Doe",
"phone_number": "+237671234567",
"email": "jane.doe@example.com",
"metadata": {
"user_id": "42"
},
"language": "fr",
"created_at": 1727600000,
"updates": {
"channel": "telegram",
"email": {
"status": "active"
},
"telegram": {
"status": "active",
"connected_at": 1727600300,
"connect_url": null
},
"whatsapp": {
"status": "off",
"connected_at": null,
"connect_url": null
}
}
}Delete a customer
DELETE/v1/apps/{appID}/customers/{id}
Deletes a customer and erases their personal details. Use it when a customer asks you to delete their data. You can't undo it.
First, each of the customer's subscriptions that hasn't ended (pending, trialing, active, or past_due) ends right away, as if you canceled it. Each one sends subscription.canceled with reason merchant, and the customer gets the usual message that their subscription ended.
Then Abuna erases the customer's name, email, phone number, Telegram and WhatsApp details, and metadata, including on their past invoices, messages, and events. The customer's ID, invoices, invoice numbers, payments, and amounts stay, so your totals don't change.
Response attributes
idstringThe customer's ID.deletedbooleanAlwaystrue.deleted_attimestampWhen the customer was deleted, in Unix seconds.
Abuna then sends customer.deleted. When you get it, delete your own copy of the customer's details. Deleting a customer that is already deleted returns the same response and sends no new events. Like other writes, it accepts an Idempotency-Key. If the app has no customer with that ID, returns 404 with code not_found.
After you delete a customer:
- Retrieving or updating them, starting a subscription for them, or creating a session for them returns
404with codenot_found. - List customers leaves them out.
- Their pay links, customer portal links, and cancel links open a page saying the link has expired.
Your secret key can always delete a customer. In the dashboard, only team owners can.
curl -X DELETE https://api.abuna.app/v1/apps/8ddhXCDW/customers/Cu5tM8rA \
-H "Authorization: Bearer sk_test_..."{
"id": "Cu5tM8rA",
"deleted": true,
"deleted_at": 1727700000
}