Pagination guide

All top-level resources in the TapTree API offer support for retrieving multiple records in batches via list API methods. For example, you can list all of your payments or refunds.

All list API methods utilize three key parameters: limit, starting_after, and ending_before. Our approach to pagination is cursor-based, where starting_after and ending_before use an object ID as a reference point. While starting_after retrieves objects after the specified ID, ending_before fetches objects before it, both in reverse chronological order. It's important to note that starting_after and ending_before are exclusive; you can use one or the other in a single query, but not both at the same time.

Pagination requests

Name
limit
Type
integer
|
Optional
optional
|
Default
default=10
Description
Sets the maximum number of items per response. Standard list responses have a default limit of 10 items, but you can increase this up to 100.
Name
starting_after
Type
string
|
Optional
optional
Description
Specifies the cursor using an object id. Use the last item ID on the current page to fetch the next page.
starting_after and ending_before are mutually exclusive, which means that if both are specified you will receive a 400 – Bad Request.
Name
ending_before
Type
string
|
Optional
optional
Description
Specifies the cursor using an object id. Use the first item ID on the current page to fetch the previous page.

Pagination request object

{
  "limit": 20,
  "starting_after": "pay_3ouMA9myA3"
}

Pagination responses

Responses are structured for clarity, items are nested under a data attribute, and has_more indicates if additional pages exist.

Name
has_more
Type
boolean
Description
Indicates if additional pages exist.
Name
data
Type
object
Description
List of objects.

Paginated response

{
  "has_more": true,
  "data": [
    // list of objects
  ]
}

Payments example

You will now see a practical example of how to paginate through a list of payments.

Requesting the first page

Let's retrieve the latest payments and set the limit attribute to retrieve the 20 most recent payments.

Requesting the first page using cURL

curl -G https://api.taptree.org/v1/payments \
  -H "Authorization: Bearer test_123" \
  -d limit=20

The list is sorted in reverse chronological order. The response also includes the has_more attribute to indicate the availability of further pages.

First page response

{
  "has_more": true,
  "data": [
    {
      "object": "payment",
      "id": "pay_Aa54Z3THuFj"
      // ...
    },
    {
      "object": "payment",
      "id": "pay_5A8hsNqGGyW"
      // ...
    },
    // ...
    // ...
    // ...
    // Last payment
    {
      "object": "payment",
      "id": "pay_2Xs7s4wm5kD"
      // ...
    }
  ]
}

Requesting the next page

To fetch payments listed after pay_2Xs7s4wm5kD, the last payment in the previous response, you can use the starting_after parameter. Again we limit the number of payments to 20.

Requesting the second page using cURL

curl -G https://api.taptree.org/v1/payments \
  -H "Authorization: Bearer {token}" \
  -d starting_after="pay_2Xs7s4wm5kD" \
  -d limit=20

The response will include the has_more attribute to indicate the availability of further pages.

Second page response

{
  "has_more": true,
  "data": [
    {
      "object": "payment",
      "id": "pay_3ouMA9myA3"
      // ...
    },
    {
      "object": "payment",
      "id": "pay_7dHxyeTnoo2"
      // ...
    },
    // ...
    // ...
    // ...
    // Last payment
    {
      "object": "payment",
      "id": "pay_4T3ktH5T4is"
      // ...
    }
  ]
}