Build Basics

Versioning in Square APIs

How Square versioning works Permalink Get a link to this section

Connect v1 APIs were released before Square implemented versioning and are therefore 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 Developer 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.

The pinned default Square-Version determines how API requests are processed by Square. The default value can be overridden by setting the Square-Version header in the HTTPS request as shown in the following example:

curl https://connect.squareupsandbox.com/v2/payments \
  -X GET \
  -H 'Content-Type: application/json' \
  -H 'Square-Version: 2020-01-22'

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 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 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.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-20191217 An example JavaScript 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).

Breaking changes Permalink Get a link to this section

Non-breaking changes can 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 following table outlines 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.

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 the 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.