Pagination

Trois styles coexistent dans l'API. Ils ne sont pas interchangeables — chaque endpoint en utilise un, et l'enveloppe de la réponse vous dit lequel.

Style	Utilisé par	Pourquoi
Pagination par page (?page=N&limit=M)	GET /transactions, GET /customers, GET /payment-links	Stable, triable par created_at, convient aux UI dashboard "page 1 sur 7"
Limit/Offset (?limit=M&offset=N)	GET /subscriptions	Permet aux workers de progresser par blocs sans état partagé
Implicite / non paginé	GET /customers/{id}/payment-tokens, GET /zapier/sample-payments	Toujours petit (cartes par client, 3 échantillons)

Tous les endpoints paginés plafonnent limit à 100 et utilisent par défaut 25 (ou 20 pour /subscriptions).

Pagination par page

GET /api/v1/transactions?page=2&limit=50&status=captured

{
  "data": [ /* jusqu'à 50 transactions */ ],
  "meta": {
    "current_page": 2,
    "last_page": 14,
    "per_page": 50,
    "total": 692
  }
}

Avancez en incrémentant page jusqu'à current_page === last_page. Filtrer par dates from / to réduit last_page.

Limit/Offset

GET /api/v1/subscriptions?status=active&limit=50&offset=100

{
  "data": [ /* jusqu'à 50 abonnements */ ],
  "total": 412,
  "limit": 50,
  "offset": 100
}

Avancez en ajoutant limit à offset jusqu'à ce que offset + limit >= total. Stable entre appels tant qu'aucun nouvel abonnement n'est inséré pendant le parcours ; pour les exports nocturnes nous recommandons de fixer une borne supérieure created_at via un filtre de date sur la ressource sous-jacente si disponible.

Choisir la taille de page

• Pour les UI interactives, utilisez 25 — réponse sous ~200 KB.
• Pour les workers / exports, préférez 100 — moins d'aller-retours.
• limit > 100 est plafonné à 100 ; vous aurez 100 lignes et per_page: 100 dans le meta.

Exemples de code

// Node — parcourir chaque abonnement actif
async function walkSubscriptions(merchantKey) {
  let offset = 0, limit = 100
  while (true) {
    const r = await fetch(
      `https://app.geniuscheckout.com/api/v1/subscriptions?status=active&limit=${limit}&offset=${offset}`,
      { headers: { Authorization: `Bearer ${merchantKey}` } },
    )
    const { data, total } = await r.json()
    for (const sub of data) yield sub
    offset += limit
    if (offset >= total) break
  }
}

// PHP — parcourir chaque transaction du mois
$page = 1;
do {
    $r = json_decode(file_get_contents(
        "https://app.geniuscheckout.com/api/v1/transactions?page={$page}&limit=100&from=2026-05-01",
        false,
        stream_context_create(['http' => ['header' => "Authorization: Bearer {$key}"]])
    ), true);
    foreach ($r['data'] as $txn) {
        // …
    }
    $page++;
} while ($page <= $r['meta']['last_page']);

Pourquoi trois styles ?

Différents endpoints ont des besoins de cohérence différents. Les lectures de tables financières (/transactions, /customers) veulent des numéros de page stables pour les tableaux de bord. Les lectures de jobs en arrière-plan (/subscriptions) veulent des curseurs offset qu'un worker peut parcourir pendant que de nouveaux enregistrements apparaissent sans en sauter. Nous avons unifié sur les deux styles qui correspondent à l'usage réel plutôt que de forcer un style unique là où il ne convient pas. Les nouveaux endpoints penchent vers limit/offset.

Suite

• Limites de débit — les endpoints de liste sont dans le tier writes