Pagination

📘

Auto-pagination helpers are available in our API libraries for easy navigation through all pages of a list.

Top-level API resources support bulk fetches through "list" API methods, such as list events, list disputes, and list settlement records. These methods have a common structure, taking at least page_size, starting_after, and ending_before as parameters.

Request parameters

• page_size: The number of records to return in the API response.
• starting_after: A cursor for pagination. Provide an item's token to fetch the next page of results that appear after this item in the list.
• ending_before: A cursor for pagination. Provide an item's token to fetch the previous page of results that appear before this item in the list.

The value provided for starting_after or ending_before should be a token of the type of resource being queried. For example, when querying the /disputes endpoint you would provide a dispute object's token as either the starting_after or ending_before value.

To navigate through pages:

• To get the next page: use starting_after with the token of the last item in your current results
• To get the previous page: use ending_before with the token of the first item in your current results

If neither starting_after or ending_before are provided, then the API will return the newest objects. Objects are always returned in reverse chronological order (newest first). starting_after and ending_before cannot be used together.

Response parameters

has_more: true when there are more records that match the API request. To access those items, update either the starting_after or ending_before parameters and send another request.

Example

// Example Request to GET /disputes using Pagination
{
  ...
  "page_size": 5,
  "starting_after": "bf3022a8-4628-4417-b4db-e1ba72075a08",
  // Returns the next page of results (older items) after this dispute in the list.
}

// Response
{
  "data": [...], // 5 items returned because of the provided "page_size" in the request.
  "has_more": true // More items exist that match the query.
  // Change the "starting_after" to the token of the last object in data
  // to receive the next page of objects.
}

// Example: If items were created in order [A,B,C,D,E], they are returned as [E,D,C,B,A]
// First page of size 3 (no cursor): returns [E,D,C]
// Next page using starting_after="C": returns [B,A]
// Previous page using ending_before="C": returns [E,D]