Versioning in Square APIs
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'
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.
For example, consider the following SDK versions:
|Example SDK version||Description|
|18.104.22.16891217||2.0.1 represents the first patch (2.0.1) to SDK version 2.0 (2.0.1) of our release.|
|22.214.171.12491217||2.2.1 represents the second minor version (2.2.1) to SDK version 2 (2.2.1) of our release.|
|126.96.36.19991217||A major version (3.0.0) represents a major breaking change.|
|3.0.0||An example .NET SDK version. It does not include 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
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.
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.
While not considered breaking changes, major releases and deprecations are also 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|
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.