# Customers > Create, list, update and delete the people who subscribe. Source: https://abuna.app/docs/api/customers 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** - `id` (string): Unique identifier for the customer. - `app_id` (string): The app the customer belongs to. - `name` (string, nullable): The customer's name. - `phone_number` (string, nullable): The 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 has `null` until they pay. Their first successful payment saves the number that paid and sends a `customer.updated` [event](https://abuna.app/docs/api/events.md#customer-updated). - `email` (string): The customer's email address. Abuna sends every message for the customer to this address. - `metadata` (object): Your 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](https://abuna.app/docs/api/subscriptions.md#metadata). - `language` (string, nullable): The language the customer reads their emails, Telegram messages, payment pages, and customer portal in: `fr` or `en`. The customer can change it on those pages. `null` until you or the customer set it: their pages then follow their browser's language, and everything else is in French. - `updates` (object): Where 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. - `channel` (string, nullable): The chat app the customer chose: `whatsapp`, `telegram`, or `null` for email only. - `email` (object): Has a `status`, always `active`. - `telegram` (object): Has a `status` and a `connected_at`. `connected_at` is the time Telegram was turned on, in Unix seconds, and `null` unless the status is `active`. The status is one of `off` (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), or `stopped` (the customer stopped it from Telegram, so messages go by email only until they turn it on again). It also has `connect_url`. While the status is `pending`, a link that turns Telegram on when the customer opens it and taps **Start**, for a **Turn on reminders** button in your app. `null` in every other status. - `whatsapp` (object): Has a `status`, a `connected_at`, and a `connect_url`, like `telegram`. `connected_at` is the time the customer confirmed WhatsApp, in Unix seconds, and `null` unless the status is `active`. The status is one of `off` (not chosen, or turned off), `active` (on, so messages go to WhatsApp too), `stopped` (the customer sent `stop` in the chat, so messages go by email only until they confirm their number again), or `failed` (the number can't get WhatsApp messages, so messages go by email only until the customer gives another number). WhatsApp is never `pending`. The customer confirms their number with a code when they choose it, so it is `active` as soon as they confirm it, and `connect_url` is always `null`. - `created_at` (timestamp): When the customer was created, in Unix seconds. **The customer object** ```json { "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` Creates a customer. **Parameters** - `email` (string, required): The customer's email address. - `phone_number` (string, required): The customer's phone number, with its country code, like `+237671234567`. - `name` (string): The customer's name. - `metadata` (object): Your own keys and values, like your user's ID. See [Metadata](https://abuna.app/docs/api/subscriptions.md#metadata) for the limits. - `language` (string): `fr` or `en`: 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`. **POST /v1/apps/{appID}/customers** cURL: ```bash 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" }' ``` Node.js: ```javascript const response = await fetch("https://api.abuna.app/v1/apps/8ddhXCDW/customers", { method: "POST", headers: { Authorization: "Bearer sk_test_...", "Content-Type": "application/json" }, body: JSON.stringify({ name: "Jane Doe", email: "jane@example.com", phone_number: "+237671234567", metadata: { user_id: "42" }, language: "fr", }), }); const customer = await response.json(); ``` Python: ```python import requests response = requests.post( "https://api.abuna.app/v1/apps/8ddhXCDW/customers", headers={"Authorization": "Bearer sk_test_..."}, json={ "name": "Jane Doe", "email": "jane@example.com", "phone_number": "+237671234567", "metadata": {"user_id": "42"}, "language": "fr", }, ) customer = response.json() ``` PHP: ```php true, CURLOPT_HTTPHEADER => ["Authorization: Bearer sk_test_...", "Content-Type: application/json"], CURLOPT_POSTFIELDS => json_encode([ "name" => "Jane Doe", "email" => "jane@example.com", "phone_number" => "+237671234567", "metadata" => ["user_id" => "42"], "language" => "fr", ]), CURLOPT_RETURNTRANSFER => true, ]); $customer = json_decode(curl_exec($ch), true); ``` Go: ```go body, _ := json.Marshal(map[string]any{ "name": "Jane Doe", "email": "jane@example.com", "phone_number": "+237671234567", "metadata": map[string]any{"user_id": "42"}, "language": "fr", }) req, _ := http.NewRequest("POST", "https://api.abuna.app/v1/apps/8ddhXCDW/customers", bytes.NewReader(body)) req.Header.Set("Authorization", "Bearer sk_test_...") req.Header.Set("Content-Type", "application/json") res, err := http.DefaultClient.Do(req) if err != nil { log.Fatal(err) } defer res.Body.Close() var customer map[string]any json.NewDecoder(res.Body).Decode(&customer) ``` **Response** ```json { "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** - `search` (string): Returns 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 45` finds `+237671234567`. - `limit` (integer): How many customers to return, from 1 to 100. Defaults to 50. - `cursor` (string): The `next_cursor` from the previous page. Send the same filters with it. **Extra attributes** - `telegram_connected` (boolean): Whether the customer gets their messages on Telegram too. - `active_subscriptions` (integer): How many of the customer's subscriptions are `active` or `past_due` (unpaid). Returns `items` and `next_cursor`, as described in [Lists and filters](https://abuna.app/docs/lists-and-filters.md#pages). A value that isn't allowed, like a `limit` above 100, returns `422` with code `invalid` and the parameter's name in `errors`. **GET /v1/apps/{appID}/customers** cURL: ```bash curl "https://api.abuna.app/v1/apps/8ddhXCDW/customers?search=ana" \ -H "Authorization: Bearer sk_test_..." ``` Node.js: ```javascript const response = await fetch("https://api.abuna.app/v1/apps/8ddhXCDW/customers?search=ana", { headers: { Authorization: "Bearer sk_test_..." }, }); const page = await response.json(); ``` Python: ```python import requests response = requests.get( "https://api.abuna.app/v1/apps/8ddhXCDW/customers?search=ana", headers={"Authorization": "Bearer sk_test_..."}, ) page = response.json() ``` PHP: ```php ["Authorization: Bearer sk_test_..."], CURLOPT_RETURNTRANSFER => true, ]); $page = json_decode(curl_exec($ch), true); ``` Go: ```go req, _ := http.NewRequest("GET", "https://api.abuna.app/v1/apps/8ddhXCDW/customers?search=ana", nil) req.Header.Set("Authorization", "Bearer sk_test_...") res, err := http.DefaultClient.Do(req) if err != nil { log.Fatal(err) } defer res.Body.Close() var page map[string]any json.NewDecoder(res.Body).Decode(&page) ``` **Response** ```json { "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`. **GET /v1/apps/{appID}/customers/{id}** cURL: ```bash curl https://api.abuna.app/v1/apps/8ddhXCDW/customers/Cu5tM8rA \ -H "Authorization: Bearer sk_test_..." ``` Node.js: ```javascript const response = await fetch("https://api.abuna.app/v1/apps/8ddhXCDW/customers/Cu5tM8rA", { headers: { Authorization: "Bearer sk_test_..." }, }); const customer = await response.json(); ``` Python: ```python import requests response = requests.get( "https://api.abuna.app/v1/apps/8ddhXCDW/customers/Cu5tM8rA", headers={"Authorization": "Bearer sk_test_..."}, ) customer = response.json() ``` PHP: ```php ["Authorization: Bearer sk_test_..."], CURLOPT_RETURNTRANSFER => true, ]); $customer = json_decode(curl_exec($ch), true); ``` Go: ```go req, _ := http.NewRequest("GET", "https://api.abuna.app/v1/apps/8ddhXCDW/customers/Cu5tM8rA", nil) req.Header.Set("Authorization", "Bearer sk_test_...") res, err := http.DefaultClient.Do(req) if err != nil { log.Fatal(err) } defer res.Body.Close() var customer map[string]any json.NewDecoder(res.Body).Decode(&customer) ``` **Response** ```json { "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](https://abuna.app/docs/api/events.md). **Parameters** - `name` (string): The customer's name. Send `null` to clear it. - `email` (string): The customer's email address. It can't be `null`. - `phone_number` (string): The customer's phone number, with its country code. Abuna saves it as `+` and digits, so `00237 671-234-567` becomes `+237671234567`. It can't be `null`. - `metadata` (object): Replaces the customer's metadata with the object you send. - `language` (string): `fr` or `en`. Send `null` to 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`. **PATCH /v1/apps/{appID}/customers/{id}** cURL: ```bash 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" }' ``` Node.js: ```javascript const response = await fetch("https://api.abuna.app/v1/apps/8ddhXCDW/customers/Cu5tM8rA", { method: "PATCH", headers: { Authorization: "Bearer sk_test_...", "Content-Type": "application/json" }, body: JSON.stringify({ email: "jane.doe@example.com", }), }); const customer = await response.json(); ``` Python: ```python import requests response = requests.patch( "https://api.abuna.app/v1/apps/8ddhXCDW/customers/Cu5tM8rA", headers={"Authorization": "Bearer sk_test_..."}, json={ "email": "jane.doe@example.com", }, ) customer = response.json() ``` PHP: ```php "PATCH", CURLOPT_HTTPHEADER => ["Authorization: Bearer sk_test_...", "Content-Type: application/json"], CURLOPT_POSTFIELDS => json_encode([ "email" => "jane.doe@example.com", ]), CURLOPT_RETURNTRANSFER => true, ]); $customer = json_decode(curl_exec($ch), true); ``` Go: ```go body, _ := json.Marshal(map[string]any{ "email": "jane.doe@example.com", }) req, _ := http.NewRequest("PATCH", "https://api.abuna.app/v1/apps/8ddhXCDW/customers/Cu5tM8rA", bytes.NewReader(body)) req.Header.Set("Authorization", "Bearer sk_test_...") req.Header.Set("Content-Type", "application/json") res, err := http.DefaultClient.Do(req) if err != nil { log.Fatal(err) } defer res.Body.Close() var customer map[string]any json.NewDecoder(res.Body).Decode(&customer) ``` **Response** ```json { "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`](https://abuna.app/docs/api/events.md#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** - `id` (string): The customer's ID. - `deleted` (boolean): Always `true`. - `deleted_at` (timestamp): When the customer was deleted, in Unix seconds. Abuna then sends [`customer.deleted`](https://abuna.app/docs/api/events.md#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`](https://abuna.app/docs/errors.md#idempotency). 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 `404` with code `not_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. **DELETE /v1/apps/{appID}/customers/{id}** cURL: ```bash curl -X DELETE https://api.abuna.app/v1/apps/8ddhXCDW/customers/Cu5tM8rA \ -H "Authorization: Bearer sk_test_..." ``` Node.js: ```javascript const response = await fetch("https://api.abuna.app/v1/apps/8ddhXCDW/customers/Cu5tM8rA", { method: "DELETE", headers: { Authorization: "Bearer sk_test_..." }, }); const deleted = await response.json(); ``` Python: ```python import requests response = requests.delete( "https://api.abuna.app/v1/apps/8ddhXCDW/customers/Cu5tM8rA", headers={"Authorization": "Bearer sk_test_..."}, ) deleted = response.json() ``` PHP: ```php "DELETE", CURLOPT_HTTPHEADER => ["Authorization: Bearer sk_test_..."], CURLOPT_RETURNTRANSFER => true, ]); $deleted = json_decode(curl_exec($ch), true); ``` Go: ```go req, _ := http.NewRequest("DELETE", "https://api.abuna.app/v1/apps/8ddhXCDW/customers/Cu5tM8rA", nil) req.Header.Set("Authorization", "Bearer sk_test_...") res, err := http.DefaultClient.Do(req) if err != nil { log.Fatal(err) } defer res.Body.Close() var deleted map[string]any json.NewDecoder(res.Body).Decode(&deleted) ``` **Response** ```json { "id": "Cu5tM8rA", "deleted": true, "deleted_at": 1727700000 } ```