Versioning in Square APIs
Square APIs use versioning to improve features without breaking your code.
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.
When a new
Square-Version is released, new SDKs are published on GitHub and various package management systems. SDK updates follow the version convention of the associated language and manager but include the related
Square-Version in the SDK version. For example, SDKs tied to version
2019-04-10 might look like
While the SDK versions map to a related
Square-Version, SDKs follow an independent, incremental versioning scheme to allow updates and improvements to the SDKs outside of
Due to string limitations for
VERSIONINFO in Windows OS, versioning for the .NET SDK follows as strict numeric iteration. Make sure to check the compatible SDK version in the most recent changelog to determine SDK compatibility.
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|
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.