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

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 {SDK_VERSION}.2019-04-10.{VERSION_INCREMENT}.

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 Square-Version updates.

Important

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.

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.