Paginação

Toda listagem da API pagina por cursor. Não existe page nem offset.

Cursor em vez de número de página não é preferência de estilo: a lista muda enquanto você a percorre. Com offset, uma cobrança nova no topo empurra tudo e a página 2 repete um item que a página 1 já trouxe. Com cursor, isso não acontece.

Como percorrer

Peça a primeira página, leia next_cursor da resposta, mande esse valor de volta em cursor na chamada seguinte, e pare quando next_cursor vier nulo.

Copiar// Percorre TODAS as cobranças pagas do período, página por página, pelo cursor.
//   LM_API_URL=... LM_API_KEY=... node list-transactions.mjs
const apiUrl = process.env.LM_API_URL;
const apiKey = process.env.LM_API_KEY;

let cursor = null;
let total = 0;

do {
  const query = new URLSearchParams({ status: 'paid', limit: '100' });
  // O cursor é opaco: mande de volta exatamente a string que veio, sem decodificar.
  if (cursor !== null) query.set('cursor', cursor);

  const res = await fetch(`${apiUrl}/v1/transactions?${query}`, {
    headers: { Authorization: `Bearer ${apiKey}` },
  });
  const pagina = await res.json();

  if (!res.ok) {
    console.error(res.status, pagina.error.code, pagina.error.request_id);
    process.exit(1);
  }

  for (const cobranca of pagina.data) {
    console.log(cobranca.id, cobranca.amount, cobranca.net, cobranca.paid_at);
    total += 1;
  }

  // `next_cursor` nulo é o fim. Nunca pare porque a página veio curta.
  cursor = pagina.next_cursor;
} while (cursor !== null);

console.log('cobranças pagas:', total);

As três regras

limit vai de 1 a 100, e o padrão é 50. Pedir mais que 100 é 400 validation_failed.

next_cursor nulo é o fim, e só ele. A última página costuma vir mais curta, mas página curta não é sinal de fim: só o next_cursor nulo é. Um laço que para quando data.length < limit perde itens.

O cursor é opaco. É uma string que você devolve exatamente como recebeu. Não decodifique, não guarde partes dela, não construa uma à mão. O formato pode mudar sem aviso; o contrato é só "mande de volta o que veio". Cursor que não decodifica responde 400 invalid_cursor.

Ordem

A ordem é fixa, da mais nova para a mais antiga, pela data de criação, com o id desempatando. Ela é a mesma em toda listagem e não é configurável.

Como o critério é estável, item criado depois de você começar a percorrer não aparece na volta: ele entra no topo, que já ficou para trás. Para acompanhar novidades, use os filtros de data ou os webhooks, não a paginação.

Filtros e totais

Os filtros de cada listagem estão na referência da operação. Dois detalhes que valem para todas:

• Filtro não muda a ordem nem o formato do cursor. Você pode paginar com filtro à vontade.
• Na listagem de cobranças, with_totals=1 acrescenta os totais do recorte filtrado, calculados sobre tudo e não só sobre a página. Os totais são idênticos em todas as páginas, então peça uma vez só, na primeira.

Próximo passo

Limites fecha os fundamentos: quantas chamadas por minuto, e o que fazer com 429.

Referência: Lista cobranças do seller e Lista os saques do seller no mode atual.