Versioning Overview
Square Connect v2 APIs use versioning to improve features without breaking your code.
How versioning works
Square API versions (Square-Version
) track changes in the evolution of Connect v2 APIs. The Square-Version
naming
scheme is YYYY-MM-DD
, which indicates the date the version was released. Connect v1 APIs are not versioned. Square
continues to support Connect v1, but future releases will focus on improving Connect v2 functionality.
By default, new Square applications are pinned to the version current at the time the application was created in the
Square Application Dashboard. Pinning an application sets the default Square-Version
for the application. The default
Square-Version
of an application can be reviewed and updated at any time on the settings pages for the application.
Versioning and SDKs
When a new Square-Version
is released, new Connect 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, Connect SDKs tied to version 2020-02-16
might look like
{SDK_VERSION}.2020-02-16.{VERSION_INCREMENT}
.
While SDK versions can be mapped to a related Square-version, SDK versions follow an independent, incremental versioning
scheme to allow updates and improvements to the SDKs outside of Square-Version
updates.
Migrating to new versions
In most cases, Square-version migration 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 the Connect v2 API request for REST calls. 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.