Skip to content
ABUNA
DocsLists and filters

Getting started

Lists and filters

What list endpoints return, how to page through and filter them, and how to treat IDs.

View as Markdown

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, or null on the last one. Treat it as opaque.
A page
{
  "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 returns 422 with code invalid and an errors item for limit.
  • cursor: the next_cursor from the page before. Send the same filters and limit with it.

Paging never skips or repeats an item, even when many items share a created_at. For events, use Catch up on missed events.

Read every page
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: status is open, paid, void, or overdue. search matches part of the number, name, or email, ignoring case. from and to bound the issue date in Unix seconds. customer_id is one customer's ID.
  • Sessions: type is checkout, payment, plan_change, cancel, or portal. status is open, completed, or expired. subscription_id is one subscription's ID.
  • Customers: search matches part of the name or email, ignoring case.
  • Subscriptions: status is pending, active, past_due, or canceled. customer_id is one customer's ID. email matches part of the customer's email, ignoring case.
  • Events: type is one event type, such as invoice.paid.
  • Webhook deliveries: type is one event type. status is pending, delivering, delivered, or failed.
  • Customer messages: subscription_id is one subscription's ID. status is pending, sending, sent, failed, or withdrawn.

Filters combine, so a list returns only items that match all of them.

GET /v1/apps/{appID}/subscriptions
curl "https://api.abuna.app/v1/apps/8ddhXCDW/subscriptions?status=active&customer_id=Cu5tM8rA" \
  -H "Authorization: Bearer sk_test_..."

Next steps