Common Square API Patterns

Learn how the Square Python SDK supports the common Square API features.

Some of the Square API patterns are used across various APIs. These include the following:

• Pagination - Many Square API operations limit the size of the response. When the result of the API operation exceeds the limit, the API truncates the result. You must make a series of requests to retrieve all the data. This is referred to as pagination.
• Idempotency key - Most Square APIs that perform create, update, or delete operations require idempotency keys to protect against making duplicate calls that can have negative consequences (for example, charging a card on file twice).
• Object versioning - Some Square resources (for example, the Customer object) have versions assigned. The version numbers enable optimistic concurrency, which is the ability for multiple transactions to complete without interfering with each other.
• Clear API object fields - Square API update endpoints that support sparse updates allow you to clear fields by setting the value to None. Note that update_order requires an X-Clear-Null: true HTTP header to indicate that the request contains a None field update.

These Square API patterns are exposed in the Square Python SDK.

Square API pagination support lets you split a full query result set into pages that are retrieved over a sequence of requests. For example, when you call client.customers.list, you can limit the number of customers returned in each response.

To iterate over all customers, you can use a for loop and the SDK makes additional HTTP requests for you to retrieve additional pages of data.

customers = client.customers.list(
    limit=10,
    sortField="DEFAULT",
    sortOrder="DESC"
)

for customer in customers:
    print(
      f"Customer: ID: {customer.id}, "
      f"Version: {customer.version}, "
      f"Given name: {customer.given_name}, "
      f"Family name: {customer.family_name}"
  )