Paginación

Tres estilos coexisten en la API. No son intercambiables — cada endpoint usa uno, y el envoltorio de la respuesta te dice cuál.

Estilo	Usado por	Por qué
Basado en páginas (?page=N&limit=M)	GET /transactions, GET /customers, GET /payment-links	Estable, ordenable por created_at, ideal para UIs de dashboard "página 1 de 7"
Limit/Offset (?limit=M&offset=N)	GET /subscriptions	Permite que workers caminen por bloques sin estado compartido
Implícita / sin paginación	GET /customers/{id}/payment-tokens, GET /zapier/sample-payments	Siempre pequeño (tarjetas por cliente, 3 muestras)

Todos los endpoints paginados topan limit en 100 y por defecto usan 25 (o 20 para /subscriptions).

Basado en páginas

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

{
  "data": [ /* hasta 50 transacciones */ ],
  "meta": {
    "current_page": 2,
    "last_page": 14,
    "per_page": 50,
    "total": 692
  }
}

Avanza incrementando page hasta current_page === last_page. Filtrar por from / to reduce last_page.

Limit/Offset

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

{
  "data": [ /* hasta 50 suscripciones */ ],
  "total": 412,
  "limit": 50,
  "offset": 100
}

Avanza sumando limit a offset hasta que offset + limit >= total. Estable entre llamadas mientras no se inserten nuevas suscripciones durante el recorrido; para exportes nocturnos recomendamos fijar un límite superior created_at vía un filtro de fecha en el recurso subyacente si está disponible.

Cómo elegir el tamaño de página

• Para UIs interactivas, usa 25 — mantiene la respuesta bajo ~200 KB.
• Para workers / exportes, prefiere 100 — menos round-trips.
• limit > 100 se topa a 100; obtendrás 100 filas y per_page: 100 en la meta.

Ejemplos de código

// Node — caminar cada suscripción activa
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 — recorrer cada transacción del mes
$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']);

¿Por qué tres estilos?

Diferentes endpoints tienen distintas necesidades de consistencia. Las lecturas de tablas de dinero (/transactions, /customers) quieren números de página estables para los dashboards de comercio. Las lecturas de jobs en segundo plano (/subscriptions) quieren cursores offset que un worker pueda recorrer mientras aparecen nuevos registros sin saltar filas. Unificamos en los dos estilos que coinciden con el uso real en lugar de forzar uno solo donde no encaja. Los endpoints nuevos se inclinan por limit/offset.

Siguiente

• Límites de tasa — los endpoints de listado están en el tier writes