Getting started
Lists and filters
What list endpoints return, how to page through and filter them, and how to treat IDs.
Every list endpoint returns its items newest first, one page at a time, in the same shape. Products, prices, customers, subscriptions, invoices, sessions, events, webhook deliveries, and customer messages (notices) all work this way.
Pages
A list returns an object with two fields:
items: the page, newest first.[]when nothing matches.next_cursor: a string to get the next page, ornullon the last one. Treat it as opaque.
{
"items": [
{ "id": "x9QbL2sK", "status": "active", "created_at": 1727600000 }
],
"next_cursor": "eDlRYkwyc0s"
}Two query parameters control paging:
limit: how many items to return, from 1 to 100. It defaults to 50. A value outside 1 to 100 returns422with codeinvalidand anerrorsitem forlimit.cursor: thenext_cursorfrom the page before. Send the same filters andlimitwith it.
Paging never skips or repeats an item, even when many items share a created_at. For events, use Catch up on missed events.
const base = "https://api.abuna.app/v1/apps/8ddhXCDW/customers?limit=100";
const headers = { Authorization: "Bearer sk_test_..." };
const customers = [];
let cursor = null;
do {
const url = base + (cursor ? "&cursor=" + encodeURIComponent(cursor) : "");
const page = await (await fetch(url, { headers })).json();
customers.push(...page.items);
cursor = page.next_cursor;
} while (cursor);The prices list includes archived prices. An archived price has a timestamp in archived_at.
IDs
Treat every ID as an opaque string. Don't parse it, and don't assume its length or what characters it has: objects created before launch can have longer IDs than new ones.
Don't sort by ID either. The one exception is event IDs, which sort in the order the events happened. See Event order.
Filters
Send filters as query parameters. The API ignores a blank filter. A status it doesn't know returns 422 with code invalid.
- Invoices:
statusisopen,paid,void, oroverdue.searchmatches part of the number, name, or email, ignoring case.fromandtobound the issue date in Unix seconds.customer_idis one customer's ID. - Sessions:
typeischeckout,payment,plan_change,cancel, orportal.statusisopen,completed, orexpired.subscription_idis one subscription's ID. - Customers:
searchmatches part of the name or email, ignoring case. - Subscriptions:
statusispending,active,past_due, orcanceled.customer_idis one customer's ID.emailmatches part of the customer's email, ignoring case. - Events:
typeis one event type, such asinvoice.paid. - Webhook deliveries:
typeis one event type.statusispending,delivering,delivered, orfailed. - Customer messages:
subscription_idis one subscription's ID.statusispending,sending,sent,failed, orwithdrawn.
Filters combine, so a list returns only items that match all of them.
curl "https://api.abuna.app/v1/apps/8ddhXCDW/subscriptions?status=active&customer_id=Cu5tM8rA" \
-H "Authorization: Bearer sk_test_..."Next steps
- SubscriptionsStart, list, read, update, cancel, keep and change the plan of a customer's subscription.
- Invoices and paymentsBilling periods, their invoices and the payments made against them. List and read invoices.
- SessionsSend a customer to a hosted page to subscribe, pay an invoice, change plan, cancel or open the customer portal. Then list, read and expire those sessions.
- EventsThe record of everything that happened in an app, and every event type.