How pagination works

Learn how to paginate results for list and search endpoints.

The Stripe API has list and search endpoints that can return multiple objects, such as listing Customers or searching for PaymentIntents. To mitigate negative impacts to performance, these endpoints don’t return all results at once. Instead, Stripe returns one page of results per API call, with each page containing up to 10 results by default. Use the limit parameter to change the number of results per page.

For example, this is an API request to list Customers, with a limit of 3:

Command Line

Select a language

cURL

Stripe CLI

Ruby

Python

PHP

Java

Node.js

.NET

No results

The response from Stripe contains one page with 3 results:

Truncated API response

{
 "data": [
 {
 "id": "cus_005",
 "object": "customer",
 "name": "John Doe"
 },
 {
 "id": "cus_004",
 "object": "customer",
 "name": "Jane Doe"
 },
 {
 "id": "cus_003",
 "object": "customer",
 "name": "Jenny Rosen"
 }
 ],
 "has_more": true,
 /* ... */
}

Keep in mind the following details when using these endpoints:

Objects are inside the data property.
Objects are in reverse chronological order, meaning the most recently created object is the first one.
The has _ more property indicates if there are additional objects that weren’t returned in this request.

Instead of looping over the data array to go through objects, you should paginate results. This prevents you from missing some objects when the has_more parameter is true.

Auto-pagination

To retrieve all objects, use the auto-pagination feature. This automatically makes multiple API calls until has_more becomes false.

Select a language

Ruby

Python

PHP

Java

Node.js

.NET

No results

# Don't put any keys in code. See https://docs.stripe.com/keys-best-practices.
# Find your keys at https://dashboard.stripe.com/apikeys.
client = Stripe::StripeClient.new('sk_test_BQokikJOvBiI2HlWgH4olfQ2')
customers = client.v1.customers.list()

customers.auto_paging_each do |customer|
 # Do something with customer
end

Note

When using auto-pagination with a list endpoint and setting ending_before, the results are in chronological order, meaning the most recently created customer is the last one.

Manual pagination

Follow these steps to manually paginate results. This process is different when calling a list endpoint or a search endpoint.

Make an API call to list the objects that you want to find.

Command Line

Select a language

cURL

Stripe CLI

Ruby

Python

PHP

Java

Node.js

.NET

No results

In the response, check the value of has_more :

If the value is false , you’ve retrieved all the objects.
If the value is true , get the ID of the last object returned, and make a new API call with the starting_after parameter set.

Repeat this step until you’ve retrieved all of the objects that you want to find.

Command Line

Select a language

cURL

Stripe CLI

Ruby

Python

PHP

Java

Node.js

.NET

No results