إنتقل إلى المحتوى الرئيسي

Pagination and list endpoints

Every list endpoint returns one page of results and a marker that points to the next page. Your client follows the marker until has_more turns false.

The list envelope​

{
"object": "list",
"url": "/v1/charges",
"has_more": true,
"data": [
{ "id": "ch_3Rsx4dDtWMrPDtgt1", "object": "charge", "amount": 2120 }
]
}
FieldMeaning
dataThe objects on this page.
has_moretrue when another page exists.
urlThe endpoint path that produced this page.

The newest object appears first. Order stays stable across pages because the cursor points at an object, not at a numeric offset.

Set the page size​

limit controls the page size and accepts 1 to 100. The default is 10, which suits an interactive dashboard and wastes round trips in a batch job.

curl -s -G https://api.stripe.com/v1/charges \
-u "$STRIPE_SECRET_KEY:" \
-d limit=100 | jq '.data | length, .has_more'

A larger page reduces request count and total latency. It also raises the memory cost and the blast radius of a failed request, so 100 fits most sync jobs.

Follow the cursor​

Read the id of the last object on the page and pass it as starting_after. Repeat until has_more is false.

curl -s -G https://api.stripe.com/v1/charges \
-u "$STRIPE_SECRET_KEY:" \
-d limit=100 \
-d starting_after=ch_3Rsx4dDtWMrPDtgt1
Node.js
async function listAllCharges() {
const charges = [];
let startingAfter;

while (true) {
const url = new URL("https://api.stripe.com/v1/charges");
url.searchParams.set("limit", "100");
if (startingAfter) url.searchParams.set("starting_after", startingAfter);

const response = await fetch(url, {
headers: { Authorization: `Bearer ${process.env.STRIPE_SECRET_KEY}` },
});

if (!response.ok) throw new Error(`Stripe returned ${response.status}`);

const page = await response.json();
charges.push(...page.data);

if (!page.has_more) break;
startingAfter = page.data.at(-1).id;
}

return charges;
}
تلميح

The official libraries ship an auto-pagination helper. Use stripe.charges.listAutoPaging() in Node, stripe.Charge.listAutoPaging() in Java, or stripe.charge.list(auto_paging=True) in Python instead of writing the loop.

Filter on the server​

A filter narrows the result set before Stripe paginates it. Filtering in the client after the fetch forces you to read the whole collection.

FilterExampleScope
Time rangecreated[gte]=1735689600&created[lt]=1738368000Charges, refunds, balance transactions
Statusstatus=availableBalance transactions
Customercustomer=cus_QyJ8...Charges, payment intents, invoices
Payoutpayout=po_1N...Balance transactions in one payout

Combine filters to keep a reconciliation job inside one page. A daily job that reads yesterday's charges with a created range rarely needs a second page.

Why the cursor beats an offset​

Offset pagination asks for page 2 at row 100. The database shifts when a new charge arrives between requests, so row 100 becomes row 101 and one record appears twice. A cursor names the last object you saw, so a new charge lands ahead of the cursor and never disturbs the walk.

Two behaviors follow from the design:

  • No page number. Stripe offers no page=2 and no total_count. Count results with your own store if you need a total.
  • No random access. Jump forward with starting_after and backward with ending_before. Neither gives you page 40 of 200.

Search endpoints paginate differently​

The search endpoints accept a query string and return a next_page token instead of an object cursor.

curl -s -G https://api.stripe.com/v1/charges/search \
-u "$STRIPE_SECRET_KEY:" \
-d query='amount>1000 AND status:"succeeded"' | jq '.next_page'

Pass the token back as page to read the next page. A response with next_page: null marks the end. Search has no starting_after, so keep the two pagination models apart in your client.

Endpoint typeCursor parameterEnd signal
Standard liststarting_afterhas_more: false
Searchpagenext_page: null

Keep bulk reads inside rate limits​

A backfill over a year of charges can issue thousands of requests. Spread the load and back off when Stripe pushes back.

  • Read one page at a time. Parallel walks over the same collection trip the concurrency limit.
  • Honor the Retry-After header on a 429. See Errors and retries.
  • Cache the last cursor in durable storage so a restart resumes instead of starting over.
  • Prefer a narrow created range over a full-collection walk.

Next steps​