Build Basics

Versioning in Square APIs

Square API refers to the REST API that Square provides to manage resources (such as orders, payments, and customers) in a Square account. Square also provides language-based SDKs that provide convenient wrappers for the Square APIs. This topic explains the version-naming scheme that Square uses for the Square API and SDKs as newer versions are published.

How Square API versioning works Permalink Get a link to this section

Square uses the YYYY-MM-DD API version-naming scheme, which indicates the date the API version was released. The API versioning scheme is used to control breaking changes.

Each application you create in the Developer Dashboard has a default API version associated with it. When you create an application (see Getting Started), Square pins the latest API version to it as the default. This default is set only when you create a new application. As new API versions are released, you might choose to pin your application to the new API version after you test the API.

When you set an access token in your request, Square assumes the API version pinned to the application.

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

You can override this default by explicitly specifying an API version in a request by adding the Square-Version request headers. This enables developers to test different API versions.

curl https://connect.squareup.com/v2/payments \
  -H 'Square-Version: 2021-05-13' \
  -H 'Authorization: Bearer <ACCESS_TOKEN>' \
  -H 'Content-Type: application/json'

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

Release notes in the developer documentation describes API changes. Developers can learn about the API changes from the release notes and test migrations by overriding the default API version by explicitly setting the preferred Square-Version in the HTTP header of REST calls to the Square API.

How SDK versioning works Permalink Get a link to this section

Square follows the Semantic Versioning scheme that uses three numbers to delineate MAJOR, MINOR, and PATCH versions of our SDK. In addition, the SDK version includes the API version (SquareAPIVersion, a date value) so you know what Square API version the SDK is related to. This version scheme enables developers to quickly recognize the impact of the Square SDK changes.

The general scheme for all SDKs, except the .NET SDK and Node.js SDK, is:

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

Due to limitations in the .NET and Node.js versioning schemes, SquareAPIVersion is not supported in their versioning schemes.

For example, consider the following SDK versions:

Example SDK version Description
2.0.1.20191217 2.0.1 represents the first patch (2.0.1) to SDK version 2.0 (2.0.1) of our release.
2.2.1.20191217 2.2.1 represents the second minor version (2.2.1) to SDK version 2 (2.2.1) of our release.
3.0.0.20191217 A major version (3.0.0) represents a major breaking change.
3.0.0 An example .NET SDK version, which does not include the SquareAPIVersion.
2.0.1 An example Node.js SDK version, which uses a hyphen before the SquareAPIVersion.

Although an SDK release is always tied to a specific Square API release, this versioning scheme enables Square to independently release updates to our SDKs. The MAJOR, MINOR, or PATCH version of an SDK can change while tied to the existing Square API release (for example, a MAJOR SDK change while the SquareAPIVersion remains the same).

Each Square SDK version is created for a specific API version. To use a newer Square API version, you must upgrade the SDK to work with new API versions.

Breaking changes Permalink Get a link to this section

Non-breaking changes can be introduced to an existing API version. The following table provides examples of what is, and is not, considered a breaking change.

Important

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

API change Breaking change
New endpoints NO
New read-only or optional fields NO
New required fields YES
New string constant NO
Deprecation NO
Retirement YES
Rename/reshape of a field, data type, or string constant YES
Change to field validations YES
Change to field type assignment YES
Change to any HTTP status code returned by an operation YES

If you have questions about Square versioning, contact Developer Support, join our Slack, or reach out to your Square Account Manager.