Square API Lifecycle

This topic outlines the lifecycle for Square APIs and establishes expectations for the various stages of development.

Available API sets

Square currently supports two API sets:

• Connect v1 APIs. The original API set released in 2014, which is currently being retired.

• Square APIs. The current API set, previously known as Connect v2.

Square APIs typically follow a path from the beta state to general availability (GA). Approaching the end of their life, they are in deprecated, maintenance, and then retired states. Deprecated functionality typically remains publicly available for 12 months before Square retires the functionality.

The Square SDKs that encapsulate Square APIs follow the same lifecycle as the APIs.

Release states

Square releases APIs in the following states:

Beta

The API is available. Minor changes can be expected between beta and general availability (GA).

Beta functionality is not intended for or supported in production environments and should not be used for such.

Beta functionality is considered stable and closely represents what is intended for final release, but fixes and updates might still be made. Functionality is released in beta to give developers an opportunity to preview and validate the intended release. Any applications you develop with beta APIs should work with their GA API equivalents with little to no change. You should fully validate your application against GA before deployment in a production environment.

Beta functionality is publicly available and breaking changes follow the normal Square API versioning process. Beta functionality is documented and clearly tagged in the Technical Reference section of the Developer resource site. More expansive beta releases (such as new core functionality and new APIs) are also covered in the Documentation section of the Developer resource site.

General availability

The API is ready for production use.

Square APIs are stable, polished, and production ready. They are fully supported with new functionality and bug fixes in subsequent releases. They are subject to published the GA service level agreement (SLA).

GA functionality is publicly available and breaking changes follow the normal Square API versioning process. GA functionality is documented in the Technical Reference section and Documentation section of the Developer resource site.

Deprecated

Bug fixes are limited and no new functionality is added. They are subject to the published GA SLA.

APIs are deprecated as the first stage toward retirement; they are typically deprecated at least 12 months before permanent retirement.

Deprecated functionality remains publicly available and fully supported, but its use is strongly discouraged for all applications, regardless of the Square-Version provided with API calls. You are discouraged from building new solutions with deprecated APIs. On deprecation, you should plan on updating or retiring existing applications that depend on the deprecated APIs.

Deprecated functionality is clearly tagged in the Documentation section and grouped together in the Technical Reference section of the Developer resource site.

If a deprecated API has a Square API replacement, the deprecated API is moved to the maintenance state when the replacement reaches GA and remains in maintenance for at least six months. If no replacement is planned, the deprecated API is move to maintenance approximately six months before retirement.

Maintenance

Critical fixes only and subject to the published GA SLA.

APIs in Maintenance adhere to the same rules as deprecated APIs but with more limited updates; only critical fixes are made during this time.

Retired

No support from Square.

Retired APIs are no longer available or supported and the technical reference documentation is archived.

Retired APIs are unavailable to all applications regardless of the Square-Version provided with API calls. REST API calls return errors for all users and retired functionality is removed from all SDKs released on, or after, the retirement date. Information about retired functionality is removed from the Technical Reference and Documentation sections of the Developer resource site. Information about retired functionality might still appear in archived versions of the Technical Reference, but the retired functionality cannot be accessed, even by applications still pinned to an older Square API version. Retired functionality might still be accessible for a period of time after the posted retirement date while Square is completing the retirement. You must assume that retired endpoints are no longer available on the retirement date.

Retirement timeline

The following APIs are currently scheduled for retirement. All endpoints and related data types retire on the dates listed in the following tables. For more information, see the associated migration guide.

Deprecated

The following endpoints are currently deprecated and scheduled to be retired as noted.

Retired

The following endpoints have been retired and are no longer supported by documentation. If you have not migrated your code to use Square API endpoints, refer to the migration guides in the table to learn about the needed migrations.

Work in progress

The following endpoints will be deprecated when corresponding functionality is available in the Square API.

Deprecated endpoints

The following endpoints are deprecated and currently scheduled for retirement, but the associated APIs are still generally available. For more information, see the associated migration guide or relevant Technical Reference entry.

Deprecated fields

The following fields are deprecated and replaced: