Skip to content
ABUNA
DocsCustomers

API reference

Customers

Create, list, update and delete the people who subscribe.

View as Markdown

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

  • idstring

    Unique identifier for the customer.
  • app_idstring

    The app the customer belongs to.
  • namestringnullable

    The customer's name.
  • phone_numberstringnullable

    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.
  • emailstring

    The customer's email address. Abuna sends every message for the customer to this address.
  • metadataobject

    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.
  • languagestringnullable

    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.
  • updatesobject

    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.
    Show child attributesHide child attributes
    • channelstringnullable

      The chat app the customer chose: whatsapp, telegram, or null for email only.
    • emailobject

      Has a status, always active.
    • telegramobject

      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.
    • whatsappobject

      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_attimestamp

    When the customer was created, in Unix seconds.
The customer object
{
  "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

  • emailstringrequired

    The customer's email address.
  • phone_numberstringrequired

    The customer's phone number, with its country code, like +237671234567.
  • namestring

    The customer's name.
  • metadataobject

    Your own keys and values, like your user's ID. See Metadata for the limits.
  • languagestring

    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 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"
  }'
Response
{
  "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

  • searchstring

    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.
  • limitinteger

    How many customers to return, from 1 to 100. Defaults to 50.
  • cursorstring

    The next_cursor from the previous page. Send the same filters with it.

Extra attributes

  • telegram_connectedboolean

    Whether the customer gets their messages on Telegram too.
  • active_subscriptionsinteger

    How many of the customer's subscriptions are active or past_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.

GET /v1/apps/{appID}/customers
curl "https://api.abuna.app/v1/apps/8ddhXCDW/customers?search=ana" \
  -H "Authorization: Bearer sk_test_..."
Response
{
  "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 https://api.abuna.app/v1/apps/8ddhXCDW/customers/Cu5tM8rA \
  -H "Authorization: Bearer sk_test_..."
Response
{
  "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

  • namestring

    The customer's name. Send null to clear it.
  • emailstring

    The customer's email address. It can't be null.
  • phone_numberstring

    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.
  • metadataobject

    Replaces the customer's metadata with the object you send.
  • languagestring

    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 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"
  }'
Response
{
  "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

  • idstring

    The customer's ID.
  • deletedboolean

    Always true.
  • deleted_attimestamp

    When 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 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 -X DELETE https://api.abuna.app/v1/apps/8ddhXCDW/customers/Cu5tM8rA \
  -H "Authorization: Bearer sk_test_..."
Response
{
  "id": "Cu5tM8rA",
  "deleted": true,
  "deleted_at": 1727700000
}

Next steps