Pagination

All top-level API resources have support for bulk fetches through “list” API methods. For example, you can list charges, list customers, and list invoices. These list API methods share a common structure and accept, at a minimum, the following three parameters: limit, starting_after, and ending_before.

Stripe’s list API methods use cursor-based pagination through the starting_after and ending_before parameters. Both parameters accept an existing object ID value (see below) and return objects in reverse chronological order. The ending_before parameter returns objects listed before the named object. The starting_after parameter returns objects listed after the named object. These parameters are mutually exclusive. You can use either the starting_after or ending_before parameter, but not both simultaneously.

Our client libraries offer auto-pagination helpers to traverse all pages of a list.

Parameters

limitoptional, default is 10
This specifies a limit on the number of objects to return, ranging between 1 and 100.

starting_afteroptional object ID
A cursor to use in pagination. starting_after is an object ID that defines your place in the list. For example, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include starting_after=obj_foo to fetch the next page of the list.

ending_beforeoptional object ID
A cursor to use in pagination. ending_before is an object ID that defines your place in the list. For example, if you make a list request and receive 100 objects, starting with obj_bar, your subsequent call can include ending_before=obj_bar to fetch the previous page of the list.

List Response Format

objectstring, value is "list"
A string that provides a description of the object type that returns.

dataarray
An array containing the actual response elements, paginated by any request parameters.

has_moreboolean
Whether or not there are more elements available after this set. If false, this set comprises the end of the list.

urlurl
The URL for accessing this list.

Response

{
  "object": "list",
  "url": "/v1/customers",
  "has_more": false,
  "data": [
    {
      "id": "cus_4QFJOjw2pOmAGJ",
      "object": "customer",
      "address": null,
      "balance": 0,
      "created": 1405641735,
      "currency": "usd",
      "default_source": "card_14HOpG2eZvKYlo2Cz4u5AJG5",
      "delinquent": false,
      "description": "New customer",
      "discount": null,
      "email": null,
      "invoice_prefix": "7D11B54",
      "invoice_settings": {
        "custom_fields": null,
        "default_payment_method": null,
        "footer": null,
        "rendering_options": null
      },
      "livemode": false,
      "metadata": {
        "order_id": "6735"
      },
      "name": "cus_4QFJOjw2pOmAGJ",
      "next_invoice_sequence": 25,
      "phone": null,
      "preferred_locales": [],
      "shipping": null,
      "tax_exempt": "none",
      "test_clock": null
    },
  ]
}

Search

Some top-level API resource have support for retrieval via “search” API methods. For example, you can search charges, search customers, and search subscriptions.

Stripe’s search API methods utilize cursor-based pagination via the page request parameter and next_page response parameter. For example, if you make a search request and receive "next_page": "pagination_key" in the response, your subsequent call can include page=pagination_key to fetch the next page of results.

Our client libraries offer auto-pagination helpers to easily traverse all pages of a search result.

Search request format

queryrequired
The search query string. See search query language.

limitoptional
A limit on the number of objects returned. Limit can range between 1 and 100, and the default is 10.

pageoptional
A cursor for pagination across multiple pages of results. Don’t include this parameter on the first call. Use the next_page value returned in a previous response to request subsequent results.

Search response format

objectstring, value is "search_result"
A string describing the object type returned.

urlstring
The URL for accessing this list.

has_moreboolean
Whether or not there are more elements available after this set. If false, this set comprises the end of the list.

dataarray
An array containing the actual response elements, paginated by any request parameters.

next_pagestring
A cursor for use in pagination. If has_more is true, you can pass the value of next_page to a subsequent call to fetch the next page of results.

total_countoptional positive integer or zero
The total number of objects that match the query, only accurate up to 10,000. This field isn’t included by default. To include it in the response, expand the total_count field.

Response

{
  "object": "search_result",
  "url": "/v1/customers/search",
  "has_more": false,
  "data": [
    {
      "id": "cus_4QFJOjw2pOmAGJ",
      "object": "customer",
      "address": null,
      "balance": 0,
      "created": 1405641735,
      "currency": "usd",
      "default_source": "card_14HOpG2eZvKYlo2Cz4u5AJG5",
      "delinquent": false,
      "description": "[email protected] for Coderwall",
      "discount": null,
      "email": null,
      "invoice_prefix": "7D11B54",
      "invoice_settings": {
        "custom_fields": null,
        "default_payment_method": null,
        "footer": null,
        "rendering_options": null
      },
      "livemode": false,
      "metadata": {
        "foo": "bar"
      },
      "name": "fakename",
      "next_invoice_sequence": 25,
      "phone": null,
      "preferred_locales": [],
      "shipping": null,
      "tax_exempt": "none",
      "test_clock": null
    }
  ]
}

Auto-pagination

Our libraries support auto-pagination. This feature allows you to easily iterate through large lists of resources without having to manually perform the requests to fetch subsequent pages.

Server-side language

# The auto-pagination feature is specific to Stripe's
# libraries and cannot be used directly with curl.

Request IDs

Each API request has an associated request identifier. You can find this value in the response headers, under Request-Id. You can also find request identifiers in the URLs of individual request logs in your Dashboard.

To expedite the resolution process, provide the request identifier when you contact us about a specific request.

Server-side language

curl https://api.stripe.com/v1/customers \
  -u sk_test_4eC39Hq...arjtT1zdp7dcsk_test_4eC39HqLyjWDarjtT1zdp7dc: \
  -D "-" \
  -X POST

Versioning

Each major release, such as Acacia, includes backwards-incompatible changes. Each monthly release adds new backwards-compatible changes and uses the same name as the last major release, indicating that it’s safe to upgrade without adopting any backwards-incompatible changes. The current version is 2024-10-28.acacia. Learn more about API upgrades and backwards compatibility For information on all API updates, view our API changelog.

You can upgrade your API version in Workbench. As a precaution, use API versioning to test a new API version before committing to an upgrade.

Server-side language

curl https://api.stripe.com/v1/charges \
  -u sk_test_4eC39Hq...arjtT1zdp7dcsk_test_4eC39HqLyjWDarjtT1zdp7dc: \
  -H "Stripe-Version: 2024-10-28.acacia"

Pagination

Parameters

limitoptional, default is 10

starting_afteroptional object ID

ending_beforeoptional object ID

List Response Format

objectstring, value is "list"

dataarray

has_moreboolean

urlurl

Search

Search request format

queryrequired

limitoptional

pageoptional

Search response format

objectstring, value is "search_result"

urlstring

has_moreboolean

dataarray

next_pagestring

total_countoptional positive integer or zero

Auto-pagination

Request IDs

Versioning