Working With APIs

Pagination

Learn about pagination and how Square endpoints paginate results.

What is pagination?
Permalink Get a link to this section

Some API endpoints paginate their responses to make the result set easier to handle. For example, if you request a list of objects that is potentially too large to handle efficiently, the endpoint will return the first batch of results along with a marker of some kind to access the next batch of results. The pagination marker could be:

  • A token or cursor that you include in subsequent requests to the endpoint either as a URL parameter or in the header of your request.

  • Standardized url parameters to indicate the current starting point, such as &page=3 or &start=100.

  • A link to a different URL for subsequent requests . The new URL usually has a token or URL parameter baked into it.

You may be able to avoid dealing with pagination by narrowing your initial request. Many APIs let you query for results based on specific criteria. For example, the ListPayments endpoint lets you query for payments based on time ranges. Requesting smaller result sets can potentially eliminate pagination in the return set and minimize the need for filtering results in your application. Working with smaller result sets can improve application response time and provide a performance boost for your application.

Pagination in Connect v1
Permalink Get a link to this section

Pagination works differently for Connect v1 endpoints and Connect v2 endpoints. In Connect v1 endpoints, paginated results include a Link field in the response header with the following format:

Link:<https://connect.squareup.com/v1/LOCATION_ID/payments?batch_token=BATCH_TOKEN>;rel='next'

To fetch the next set of results, send a followup request (including all usual headers) to the next URL. When the endpoint sends the final set of results, the response will not include a next URL.

Important

The batch_token parameter included in the next URL is a short-lived token that should be used only once to fetch the next set of results for a particular query. Do not persist or reuse this value.

Pagination in Connect v2
Permalink Get a link to this section

Pagination works differently for Connect v1 endpoints and Connect v2 endpoints. In Connect v2 endpoints, paginated results include a cursor field as part of the response body.

To fetch the next set of results, send a followup request to the same endpoint and provide the cursor value returned in the previous response as a query parameter. When the endpoint sends the final set of results, the response body will not include a cursor field.

For example, consider the Labor API which includes a SearchShifts endpoint that may return an overwhelming number of Shift records depending on the search filters provided. By default, Connect v2 APIs limit the number of returned results (the page size) to 200 resources. But requests to the SearchShifts endpoint include a limit field that sets an explicit page size for the response:

    $searchShiftsRequest = new SquareConnect\model\SearchShiftsRequest();
    $searchShiftsRequest->setLimit(20);
    $searchShiftsResponse = $laborApi->searchShifts($searchShiftsRequest);

If the search results in more than 20 resources, the endpoint paginates the response and includes a cursor field. The application can call SearchShifts and use the previous request, plus the cursor, to retrieve the remaining resources in pages of 20:

  while ($searchShiftsResponse->getCursor()) {
    // Do something with the current batch of response records
    ...
    // Get the next batch of 20 records
    $searchShiftsRequest->setCursor($searchShiftsResponse->getCursor());
    $searchShiftsResponse = $laborApi->searchShifts($searchShiftsRequest);
  }