Versioning in the Square API

Describes versioning and version-naming schemes used for the Square API and SDKs.

The Square API is a collection of RESTful APIs that provide access to payments, orders, customers, and other resources in a Square account. Instead of calling the APIs directly, developers can optionally use backend platform SDKs in common programming languages.

Square API and SDK versions are updated with every release, typically on a monthly basis. Each release uses a single Square API version number that applies to all Square APIs and might contain major, minor, and patch-level updates. You can check the release notes for each API version to decide whether you should upgrade to a newer version. For example, you might decide to upgrade to access new and improved features, get bug fixes, or migrate from deprecated functionality. Note that upgrading to a new version includes all the changes across APIs that were released since your previous version and might require changes to your code.

Square APIs follow a lifecycle that can include Beta, General Availability (GA), Deprecated, and Retired stages. In a given API version, individual Square APIs and their components (such as endpoints, objects, fields, or webhooks) can be in any lifecycle stage.

New functionality might be released in Beta to allow developers to integrate and test before GA. APIs might be replaced with improved APIs, and then deprecated and eventually retired. For more information about each stage, see Square API Lifecycle.

The Square API uses a YYYY-MM-DD version-naming scheme that indicates the date the API version is released. This versioning scheme is used to control breaking changes and allows you to test newer API versions before upgrading your application. The API version applies to all Square APIs, such as the Payments API, Orders API, and Customers API.

Each application registered in the Developer Console has a default API version, which you can view or change on the Credentials page for the production or Sandbox environment. The default API version is pinned to the application and used for all API requests unless overridden in the Square-Version header.

The following request omits the Square-Version header, which directs Square to use the default API version:

curl https://connect.squareup.com/v2/payments \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json'

To override the default and test different API versions, explicitly specify the API version in the Square-Version header (or corresponding SDK client parameter):

curl https://connect.squareup.com/v2/payments \
  -H 'Square-Version: 2024-07-17' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json'

You can review the release notes to learn about changes in API versions.

The backend platform Square SDKs are provided in several common programming languages. These SDKs follow the Semantic Versioning scheme that uses three numbers to delineate MAJOR, MINOR, and PATCH versions of the SDKs.

The Java SDK, Ruby SDK, Python SDK, and PHP SDK use the following versioning scheme.