Versioning in the Square API

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

Link to section

Overview

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. You can check the release notes for each API version to decide whether you should upgrade to a newer version. For example, you might want 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 of the changes across APIs that were released since your previous version.

Note

Square graphs used in GraphQL queries generally reflect the latest version of the corresponding Square APIs.

Link to section

How Square API versioning works

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.

Note

Regardless of whether you explicitly specify a version in the request, the response always returns the Square-Version header so you know which API version is used.

Link to section

Square SDK 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.

<MAJOR>.<MINOR>.<PATCH>.<SquareAPIVersion>

SquareAPIVersion is a date value that represents that Square API version, so you know which API version the SDK supports. This versioning scheme enables developers to quickly recognize the impact of Square SDK changes.

The .NET SDK and Node.js SDK use the following versioning scheme. Note that SquareAPIVersion is not included.

<MAJOR>.<MINOR>.<PATCH>

For example, consider the following SDK versions:

Example SDK versionDescription
2.0.1.201912172.0.1 represents the first patch (2.0.1) to SDK version 2.0 (2.0.1).
2.2.1.201912172.2.1 represents the second minor version (2.2.1) to SDK version 2 (2.2.1).
3.0.0.20191217A major version (3.0.0) indicates that the release includes a breaking change.

Although SDK releases typically coincide with the release of a Square API version, this versioning scheme enables Square to independently release updates to Square SDKs. The MAJOR, MINOR, or PATCH version of an SDK can change while still tied to the existing Square API release. For example, Square can release an SDK with a MINOR version change while SquareAPIVersion remains the same.

Each Square SDK version is created for a specific API version. You must upgrade the SDK version if you want to use functionality added in a newer Square API version.

Link to section

Breaking versus non-breaking changes

Breaking changes in the Square API are introduced in versioned releases (with a new major API version). Non-breaking changes can be introduced to an existing API version. The following table provides examples of breaking and non-breaking changes.

Important

While not considered breaking changes, major releases and deprecations are versioned for easier identification.

API changeBreaking change
New endpointsNo
New read-only or optional fieldsNo
New required fieldsYes
New string constantNo
DeprecationNo
RetirementYes
Rename/reshape of a field, data type, or string constantYes
More restrictive change to field validationsYes
Less restrictive change to field validationsNo
Change to field type assignmentYes
Change to the HTTP status code returned by an operationYes

If you have questions about Square versioning, contact Developer Support, join our Discord community, or reach out to your Square account manager.

Link to section

See also