Pagination

Pagination is a process used to divide a large dataset into smaller chunks (pages). All Square API endpoints that return a list of resources support pagination. For example, the SearchCustomers endpoint (Customers API) and ListCustomerRefunds endpoint (Refunds API) support pagination. Each request to these endpoints returns a page of the result set.

When the result is truncated (there are more resources to retrieve), the response also returns a cursor field.

For example, suppose your SearchCustomers result set is 100 customers but the page returned in the response has only 10 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, you continue to send SearchCustomers requests (in each request include the cursor returned in the previous response). The last page of the result set doesn't include a cursor.

Link to section

Page limitations

All Square API endpoints that support pagination also support a limit field that the application can use to indicate the page size (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.

Link to section

Specifying cursor and page sizes

In your initial call to a paginated 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 using a limit. The following applies when specifying cursor and limit fields in these endpoint requests:

• POST requests - Include the cursor and limit fields in the request body. For example, SearchCustomers is a POST request. The following SearchCustomers request specifies a limit of 2 customers in the response. Note that the limit is set in the request body.

  Copy

  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8

  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.

  Copy

  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11

  {
    "customers": [
      {
        …
      },
      {
        …
      }
    ],
    "cursor": "Cg1HRUY3NEszUERFME40GgAiQAgCEjxDQUlRQWhva056ZzVNakUyWWpjdE5qaGxaQzAwWldRNUxUbG1ZelF0WmpSaE9EVTFaV0ZpTUdabElDbz0qBAgBEAE="
  }
  

  In your subsequent SearchCustomers request, use the same request body as before, but include the cursor in the body as shown:

  Copy

  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9

  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).

• 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 a limit of 2 refunds in the response:

  Copy

  • 1
  • 2
  • 3
  • 4

  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.

  Copy

  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11

  {
    "refunds": [
      {
        …
      },
      {
        …
      }
    ],
    "cursor": "N4LMZ7RPBUxbVBZccouiIhlFDJ1S3Dy7VsMVMookk2599EUNUaturj6EVXpslxjWc27YUXzDIYPP9O6bImVn1rvUJH98eyyAfsXLIIkYx7mM4UEXZQRcvjSuhHf"
  }
  

  You then send a subsequent request to retrieve the next set of refunds by adding cursor as query parameter.

  Copy

  • 1
  • 2
  • 3
  • 4

  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 the GetPaymentRefunds request. Eventually, there are no more refunds to return and the last response doesn't include the cursor field.

Link to section

SDK examples

The Square SDK documentation provides libraries and sample code for several programming languages. For examples of paginated requests, see the following:

• Java

• .NET

• Node.js

• PHP

• Python

• Ruby

Link to section

Pagination in Connect V1

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 retrieve 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 doesn't include the next URL.

Link to section

Additional Square API patterns

There are other Square API patterns. For more information, see Common Square API Patterns.