Versioning in Square APIs
The Square API is 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.
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 Get 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.
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.
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).
Square follows the Semantic Versioning scheme that uses three numbers to delineate
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 Square SDK changes.
The general scheme for all SDKs, except the .NET SDK and Node.js SDK, is:
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|
|188.8.131.5291217||2.0.1 represents the first patch (2.0.1) to SDK version 2.0 (2.0.1) of our release.|
|184.108.40.20691217||2.2.1 represents the second minor version (2.2.1) to SDK version 2 (2.2.1) of our release.|
|220.127.116.1191217||A major version (3.0.0) represents a major breaking change.|
|3.0.0||An example .NET SDK version, which does not include
|2.0.1||An example Node.js SDK version, which uses a hyphen before
Although an SDK release is always tied to a specific Square API release, this versioning scheme enables Square to independently release updates to the Square SDKs. The
PATCH version of an SDK can change while tied to the existing Square API release (for example, a
MAJOR SDK change while
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.
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.
While not considered breaking changes, major releases and deprecations are versioned for easier identification.
|API change||Breaking change|
|New read-only or optional fields||NO|
|New required fields||YES|
|New string constant||NO|
|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|