Listes et filtres

Chaque endpoint de liste renvoie ses éléments du plus récent au plus ancien, une page à la fois, sous la même forme. Produits, tarifs, clients, abonnements, factures, sessions, événements, livraisons de webhooks et notifications fonctionnent tous ainsi.

Pages

Une liste renvoie un objet à deux champs :

• items : la page, du plus récent au plus ancien. [] quand rien ne correspond.
• next_cursor : une chaîne pour obtenir la page suivante, ou null sur la dernière. Traitez-la comme opaque.

{
  "items": [
    { "id": "x9QbL2sK", "status": "active", "created_at": 1727600000 }
  ],
  "next_cursor": "eDlRYkwyc0s"
}

Deux paramètres de requête contrôlent la pagination :

• limit : combien d'éléments renvoyer, de 1 à 100. Par défaut : 50. Une valeur en dehors de 1 à 100 renvoie 422 avec le code invalid et un élément errors pour limit.
• cursor : le next_cursor de la page précédente. Envoyez les mêmes filtres et le même limit avec.

La pagination ne saute ni ne répète jamais un élément, même quand beaucoup d'éléments partagent un created_at. Pour les événements, voir Rattraper les événements manqués.

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);

La liste des tarifs inclut les tarifs archivés. Un tarif archivé a un horodatage dans archived_at.

Identifiants

Traitez chaque identifiant comme une chaîne opaque. Ne l'analysez pas, et ne présumez ni de sa longueur ni de ses caractères : les objets créés avant le lancement peuvent avoir des identifiants plus longs que les nouveaux.

Ne triez pas non plus par identifiant. La seule exception est les identifiants d'événement, qui se trient dans l'ordre où les événements se sont produits. Voir Ordre des événements.

Filtres

Envoyez les filtres comme paramètres de requête. L'API ignore un filtre vide. Un status qu'elle ne connaît pas renvoie 422 avec le code invalid.

• Factures : status vaut open, paid, void ou overdue. search correspond à une partie du numéro, du nom ou de l'e-mail, sans tenir compte de la casse. from et to bornent la date d'émission en secondes Unix. customer_id est l'ID d'un client.
• Sessions : type vaut checkout, payment, plan_change, cancel ou portal. status vaut open, completed ou expired. subscription_id est l'ID d'un abonnement.
• Clients : search correspond à une partie du nom ou de l'e-mail, sans tenir compte de la casse.
• Abonnements : status vaut pending, active, past_due ou canceled. customer_id est l'ID d'un client. email correspond à une partie de l'e-mail du client, sans tenir compte de la casse.
• Événements : type est un type d'événement, comme invoice.paid.
• Livraisons de webhooks : type est un type d'événement. status vaut pending, delivering, delivered ou failed.
• Notifications : subscription_id est l'ID d'un abonnement. status vaut pending, sending, sent, failed ou withdrawn.

Les filtres se combinent, une liste ne renvoie donc que les éléments qui correspondent à tous.

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