Square API Lifecycle

Learn about the Square API lifecycle and what to expect for each stage of development.

Square APIs typically follow a path from Beta to General Availability (GA). As an API approaches the end of life, Square deprecates it. While deprecated, the API remains in maintenance mode and is then retired. The Square SDKs that encapsulate Square APIs follow the same lifecycle as the APIs. The following sections describe the Square API release states.

The API is publicly available. Minor changes can be expected between Beta and General Availability (GA), so you should be prepared to upgrade your API version as needed to incorporate fixes, improvements, and new features.

The interfaces are considered stable and closely represent what Square intends for final release, but fixes and updates to the interfaces might still be made. New functionality is released in Beta to give developers an earlier opportunity to integrate and validate the intended release. Any applications you develop with Beta APIs should work with their GA API equivalents with little to no change. As a best practice, you should fully validate your application after upgrading your API version.

Beta functionality is publicly available and breaking changes follow the normal Square API versioning process. Beta functionality is documented and clearly tagged in the developer documentation.

The API is ready for production use.

Square APIs are stable, polished, and production ready. They're fully supported with new functionality and bug fixes in subsequent releases.

GA functionality is publicly available and breaking changes follow the normal Square API versioning process. GA functionality is documented in the developer documentation. GA APIs might include objects, fields, enums, and values that are in a Beta or Deprecated state.

Bug fixes are limited and no new functionality is added.

APIs are deprecated as the first stage toward retirement. They're 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're discouraged from building new solutions with deprecated APIs. On deprecation, you should plan on updating existing applications that depend on the deprecated APIs.

Deprecated functionality is clearly tagged in the developer documentation and lists deprecated APIs, deprecated endpoints, and deprecated objects, fields, enums, and values.

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

No support from Square.

Retired APIs are no longer available or supported and the API Reference documentation is archived. For information about the retirement timeline for APIs, see Migrate from Deprecated APIs.

Retired API endpoints are unavailable to all applications and return 410 GONE errors for all requests regardless of the Square-Version used for the request. Retired endpoints are removed from all SDKs released on or after the retirement date. Information about retired functionality is removed from the developer documentation on or after the retirement date, though information about retired functionality might still appear in previous versions of the API Reference. Retired functionality might still be accessible for a period of time after the posted retirement date while Square completes the retirement process. You must assume that retired endpoints are no longer available on the retirement date.

Retired objects, fields, enums, and values in public APIs remain available in API versions released prior to their retirement date.