Build Basics

Versioning in Square APIs

Square APIs use versioning to improve features without breaking your code.

How Square versioning works
Permalink Get a link to this section

Connect v1 APIs were released before Square implemented versioning and are not versioned.

Square APIs use a Square-Version header to control breaking changes over time. The Square-Version naming scheme is YYYY-MM-DD, which indicates the date the version was released.

Square pins newly created applications in the Application Dashboard to the most recent Square-Version. Pinning an application sets a default Square-Version for the application, which can be reviewed and updated at any time on the settings pages for the application.

Versioning and SDKs
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 also 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 impact of the Square SDK changes.

The general scheme for all SDKs except the .NET SDK and JavaScript SDK is:

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

Due to limitations in the .NET and JavaScript versioning schemes, SquareAPIVersion is not supported in the .NET SDK versioning scheme, and the JavaScript SDK scheme uses a hyphen in place of the last period.

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.0) to SDK version 2 (2.0.0) of our release.
3.0.0.20191217 A major version 3.0 represents a major breaking change.
3.0.0 An example .NET SDK version. It does not include the SquareAPIVersion.
2.0.1-20191217 An example JavaScript SDK version. It 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. For example, the MAJOR, MINOR, or PATCH version of an SDK can change while the SquareAPIVersion remains the same.

Breaking changes
Permalink Get a link to this section

Non-breaking changes may be introduced to an existing API version, but updates to Beta and GA functionality for Square APIs are versioned if those updates are considered breaking changes. The table below outlines what is, and is not, considered a breaking change.

Important

While not considered breaking changes, major releases and deprecations are also 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

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

Migrating to new versions
Permalink Get a link to this section

In most cases, migrating to a new Square-Version should be straightforward, with known differences listed in the related changelog.

To test migrations, developers can override the default Square-Version of an application by explicitly setting the preferred Square-Version in the HTTP header of REST calls to Square API. Requesting an API version that does not exist returns an error. Successful API responses include the Square-Version header to indicate the API version used to process request.

Connect SDK versions are locked to specific API versions and cannot be overwritten. Instead, the SDK must be upgraded to work with new API versions.