Skip to content
Create account
or
Sign in
The Stripe Docs logo
/
Ask AI
Create account
Sign in
Get started
Payments
Finance automation
Platforms and marketplaces
Money management
Developer tools
Get started
Payments
Finance automation
Get started
Payments
Finance automation
Platforms and marketplaces
Money management
Overview
Versioning
Changelog
Upgrade your API version
Upgrade your SDK version
Developer tools
SDKs
API
    API v2
    API keys
    Stripe-Context header
    Daily changelog
    Rate limits
    Automated testing
    Metadata
    Expanding responses
    Pagination
    Domains and IP addresses
    Search
    Localization
    Error handling
    Error codes
Testing
Workbench
Event Destinations
Workflows
Stripe CLI
Stripe Shell
Developers Dashboard
Agent toolkit
Stripe health alertsBuild with LLMsStripe for Visual Studio CodeFile uploads
Security
Security
Extend Stripe
Stripe Apps
Stripe Connectors
Partners
Partner ecosystem
Partner certification
HomeDeveloper toolsAPI

How pagination works

Learn how to paginate results for list and search endpoints.

Copy page

Video tutorials

To learn about pagination with video tutorials, see this playlist.

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
cURL
curl -G https://api.stripe.com/v1/customers \ -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:"
\ -d limit=3

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.

Ruby
customers = Stripe::Customer.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.

  1. Make an API call to list the objects that you want to find.
Command Line
cURL
curl https://api.stripe.com/v1/customers \ -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:"
  1. 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
cURL
curl -G https://api.stripe.com/v1/customers \ -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:"
\ -d starting_after={{LAST_CUSTOMER_ID}}
Was this page helpful?
YesNo
Need help? Contact Support.
Join our early access program.
Check out our changelog.
Questions? Contact Sales.
LLM? Read llms.txt.
Powered by Markdoc