Listas

As listas que podem ser longas (os produtos, as variantes, os pedidos) vêm em páginas, por cursor:

{ "data": [...], "next_cursor": "WyIyMDI2LTEwLTAzIDE4OjA1OjAwLjEyMzQ1NiswMCIsIjVlMmEuLi4iXQ" }

limit escolhe o tamanho da página: de 1 a 100, 50 sem ele.
next_cursor é null na última página. Para a próxima, repita a chamada com os mesmos filtros e cursor=<next_cursor>. O cursor é opaco: não monte nem mude.
O cabeçalho Link traz o endereço da próxima página pronto (<...>; rel="next"), quando há.
Sem total: contar todos a cada página pesaria nas lojas grandes. A contagem é uma rota à parte (GET /products/count, GET /orders/count).

As listas pequenas (os temas, as coleções, as marcas) cabem numa página só e vêm com next_cursor: null.

Sincronização incremental

Os produtos, as variantes e os pedidos vêm na ordem da última mudança (updated_at), da mais antiga à mais nova. Para manter uma cópia em dia sem ler tudo de novo:

leia todas as páginas uma vez e guarde o updated_at do último item;
da próxima vez, peça updated_at_min=<esse updated_at> e siga as páginas.

A data entra na lista (o último item lido vem de novo, e pode ser ignorado), e um item que muda enquanto você pagina vai para o fim e aparece de novo mais adiante. As datas são ISO 8601 (2026-10-03T18:05:00.000Z; num endereço, codifique o + de um fuso como %2B).