Learn how Square API endpoints use pagination to efficiently provide listing results.
Pagination is a process used to divide a large dataset into smaller chunks (pages). Most Square API endpoints that return a list of resources also support API pagination, such as SearchCustomers
and ListPaymentRefunds
. Each request to these endpoints returns a page of the result set.
When the result is truncated and there are more resources to retrieve, the response also returns a cursor
field. For example, suppose your SearchCustomers
result set is 500 customers but the page returned in the response has only 100 customers. In this case, the response includes a cursor
.
In your subsequent SearchCustomers
request, include the cursor
along with the same original request body to retrieve the next page (next set of customers). As long as each call results in a response that includes a cursor
, continue to send a SearchCustomers
request and include the cursor
returned in the previous response. The last page of the result set doesn't include a cursor
.
All Square API endpoints that support API pagination also support a limit
field that the application can use to indicate the page size, which is the number of items to return in the response. If you don't specify a limit
, the default limit applies. The default
and maximum
page sizes vary from one endpoint to another. The Square API technical reference provides page size details for each paging endpoint.
A page of retrieved records has a limited lifespan. Pages can become stale when other endpoints add, update, or delete records, which changes the set of returned records if a given page is requested again.
In your initial call to a paginated API endpoint, there's no need to include a cursor
: the first page of results is returned. Optionally, you can constrain the number of results returned by using the limit
field. The following guidance applies when specifying cursor
and limit
fields in these endpoint requests:
POST requests - Include the
cursor
andlimit
fields in the request body. For example, SearchCustomers is a POST request. The followingSearchCustomers
request specifies a limit of 2 customers in the response. Note that thelimit
is set in the request body.curl https://connect.squareupsandbox.com/v2/customers/search \ -X POST \ -H 'Square-Version: 2021-12-15' \ -H 'Authorization: Bearer {ACCESS_TOKEN}' \ -H 'Content-Type: application/json' \ -d '{ "limit": 2 }'The sample response shows a
cursor
in the response, indicating that there are more customers to retrieve.{ "customers": [ { "id": "JDKYHBWT1D4F8MFH63DBMEN8Y4", ... }, { "id": "A9641GZW2H7Z56YYSD41Q12HDW", ... } ], "cursor": "Cg1HRUY3NEszUERFME40GgAiQAgCEjxDQUlRQWhva056ZzVNakUyWWpjdE5qaGxaQzAwWldRNUxUbG1ZelF0WmpSaE9EVTFaV0ZpTUdabElDbz0qBAgBEAE=" }In your subsequent
SearchCustomers
request, use the same request body as before, but include thecursor
in the body as shown:curl https://connect.squareupsandbox.com/v2/customers/search \ -X POST \ -H 'Square-Version: 2021-12-15' \ -H 'Authorization: Bearer {ACCESS_TOKEN}' \ -H 'Content-Type: application/json' \ -d '{ "limit": 2, "cursor": "Cg1HRUY3NEszUERFME40GgAiQAgCEjxDQUlRQWhva056ZzVNakUyWWpjdE5qaGxaQzAwWldRNUxUbG1ZelF0WmpSaE9EVTFaV0ZpTUdabElDbz0qBAgBEAE=" }'Note that each request can specify a different page size (the
limit
field value).Important
A cursor has a 5-minute lifetime. If you cache the cursor for each page you retrieve, you can use one of these page cursors to retrieve a previous page again. However, after a cursor expires, it can no longer be used.
GET requests - The GET requests don't have a body. Therefore, you include a cursor as a query parameter. For example, ListPaymentRefunds is a GET request. The following
GetPaymentRefund
request specifies alimit
of 2 refunds in the response:curl https://connect.squareupsandbox.com/v2/refunds?limit=2 \ -H 'Square-Version: 2021-12-15' \ -H 'Authorization: Bearer {ACCESS_TOKEN}' \ -H 'Content-Type: application/json'The sample response includes a
cursor
indicating that there are more refunds to retrieve.{ "refunds": [ { "id": "bP9mAsEMYPUGjjGNaNO5ZDVyLhSZY_69MmgHubkLqx9wGhnmenRUHOaKitE6llfZuxcWYjGxd", ... }, { "id": "zVeulROORfDGNPr6ZG8BoudKQxKZY_1Ccko7Wv71jXw9OZ8f8RQlfGOX66ijLA8jxtKXwZe2Q", ... } ], "cursor": "N4LMZ7RPBUxbVBZccouiIhlFDJ1S3Dy7VsMVMookk2599EUNUaturj6EVXpslxjWc27YUXzDIYPP9O6bImVn1rvUJH98eyyAfsXLIIkYx7mM4UEXZQRcvjSuhHf" }You then send a subsequent request to retrieve the next set of refunds by adding
cursor
as query parameter.curl https://connect.squareupsandbox.com/v2/refunds?limit=2&cursor=N4LMZ7RPBUxbVBZccouiIhlFDJ1S3Dy7VsMVMookk2599EUNUaturj6EVXpslxjWc27YUXzDIYPP9O6bImVn1rvUJH98eyyAfsXLIIkYx7mM4UEXZQRcvjSuhHf \ -H 'Square-Version: 2021-12-15' \ -H 'Authorization: Bearer {ACCESS_TOKEN}' \ -H 'Content-Type: application/json'As long as the response includes a
cursor
, you continue to make theGetPaymentRefunds
request. Eventually, there are no more refunds to return and the last response doesn't include thecursor
field.
The Square SDK documentation provides libraries and sample code for several programming languages. For examples of paginated API requests, see the following:
There are other Square API patterns in addition to API pagination. For more information, see Common Square API Patterns.