Versioning in Square APIs
The Square API is a collection of RESTful APIs that developers can use to manage resources in a Square account, such as orders, payments, and customers. Square also provides convenient wrapper SDKs that enable developers to call the Square API in several common programming languages. This topic describes the version-naming schemes used for the Square API and SDKs.
The Square API uses the
YYYY-MM-DD version-naming scheme, which indicates the date that the API version is released. This versioning scheme is used to control breaking changes and lets you test newer API versions before upgrading. The API version applies to all Square APIs, such as the Payments API, Orders API, and Customers API.
Each application that you create in the Developer Dashboard has a default API version, which you can view or update on the Credentials page. The default API version is pinned to the application and used for all requests unless overridden by the
The following request doesn't include the
Square-Version header, which directs Square to use the API version pinned to the application.
You can override the default by explicitly specifying an API version in the
Square-Version header in your request. This feature enables developers to test different API versions.
Regardless of whether you explicitly specify a version in the request, the response always returns the
Square-Version header so you know which API version is used.
The release notes describe the changes in each API version. After learning about changes from the release notes, you can test migrations by explicitly specifying the preferred
Square-Version in your requests.
The Square SDKs follow the Semantic Versioning scheme that uses three numbers to delineate
PATCH versions of the SDKs.
The Java SDK, Ruby SDK, Python SDK, and PHP SDK use the following versioning scheme.
SquareAPIVersion is a date value that represents that Square API version, so you know which API version the SDK supports. This version scheme enables developers to quickly recognize the impact of Square SDK changes.
The .NET SDK and Node.js SDK use the following versioning scheme. Note that
SquareAPIVersion is not included.
For example, consider the following SDK versions:
|Example SDK version||Description|
|220.127.116.1191217||2.0.1 represents the first patch (2.0.1) to SDK version 2.0 (2.0.1).|
|18.104.22.16891217||2.2.1 represents the second minor version (2.2.1) to SDK version 2 (2.2.1).|
|22.214.171.12491217||A major version (3.0.0) indicates that the release includes a breaking change.|
Although SDK releases typically coincide with the release of a Square API version, this versioning scheme enables Square to independently release updates to Square SDKs. The
PATCH version of an SDK can change while still tied to the existing Square API release. For example, Square can release an SDK with a
MINOR version 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.
Breaking changes in the Square API are introduced in versioned releases (with a new major API version). Non-breaking changes can be introduced to an existing API version. The following table provides examples of breaking and non-breaking changes.
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|
|More restrictive change to field validations||Yes|
|Less restrictive change to field validations||No|
|Change to field type assignment||Yes|
|Change to the HTTP status code returned by an operation||Yes|