Working With APIs

Pagination

Learn about pagination and how you can use it to manage large requests.

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 returns 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 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 component.

You might 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 the Square API
Permalink Get a link to this section

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

To fetch the next set of results, send a follow-up 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 does not include a cursor field.

For example, consider the Labor API, which includes a SearchShifts endpoint that might return an overwhelming number of Shift records depending on the search filters provided.

Page size
Permalink Get a link to this section

Square APIs can limit the number of results returned from a request (the page size). When a Square endpoint lets the client set the page size, a limit query parameter is available in the request. If the client requests a larger page size than allowed by the endpoint, the endpoint returns its maximum page size. For example, the client asks for a page size of 1000 from an endpoint that allows a maximum page size of 200. The response page size is up to 200. If more results can be returned, the response contains a cursor.

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.

Page size example
Permalink Get a link to this section

Requests to the SearchShifts endpoint include a limit field that sets an explicit page size for the response:

curl https://connect.squareupsandbox.com/v2/labor/shifts/search \
  -X POST \
  -H 'Square-Version: 2020-05-28' \
  -H 'Authorization: Bearer {{AUTH TOKEN}}' \
  -H 'Content-Type: application/json' \
  -d '{
    "limit": 1
  }'

Response

{
  "shifts": [
    {
      "id": "B7EFPDYFBBB46",
      "employee_id": "aK7PdOx5RO1QxXjgr1Eo",
      "location_id": "{{LOCATION ID}}",
      "timezone": "America/Los_Angeles",
      "start_at": "2019-02-07T04:00:00-08:00",
      "end_at": "2019-02-07T11:00:00-08:00",
      "wage": {
        "hourly_rate": {
          "amount": 0,
          "currency": "USD"
        }
      },
      "status": "CLOSED",
      "version": 1,
      "created_at": "2020-06-01T16:55:34-07:00",
      "updated_at": "2020-06-01T16:55:34-07:00"
    }
  ],
  "cursor": "WhXCv79IGxSkmPNEhVUKHBuTOuRIZoUcX5VQlQBqs0AIqRD6fED"
}

If the search results is more than the requested limit, 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 1:

curl https://connect.squareupsandbox.com/v2/labor/shifts/search \
  -X POST \
  -H 'Square-Version: 2020-05-28' \
  -H 'Authorization: Bearer {{AUTH TOKEN}}' \
  -H 'Content-Type: application/json' \
  -d '{
    "limit": 1,
    "cursor": "WhXCv79IGxSkmPNEhVUKHBuTOuRIZoUcX5VQlQBqs0AIqRD6fED"
  }'

Pagination in Connect v1
Permalink Get a link to this section

Pagination works differently for Connect v1 endpoints and Square API 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 follow-up request (including all the usual headers) to the next URL. When the endpoint sends the final set of results, the response does 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.