Build Basics

Square API Lifecycle

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

Available API sets Permalink Get a link to this section

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 Permalink Get a link to this section

Square releases APIs in the following states:

Beta Permalink Get a link to this section

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 Permalink Get a link to this section

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 Permalink Get a link to this section

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.

Important

You are strongly encouraged to migrate existing users to the applicable replacements as soon as possible to avoid disrupting their commerce. Developers using Square SDKs released on, or after, the deprecation date see deprecation warnings in API logs (for interpreted languages) or compilation warnings (for compiled languages) when referencing deprecated functionality.

Maintenance Permalink Get a link to this section

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 Permalink Get a link to this section

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 Permalink Get a link to this section

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 Permalink Get a link to this section

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

V1 Collection
Replacements
Deprecation
Retirement
V1 BatchingVarious
Migration guide
2019-11-202021-09-15
V1 Employees.Employees Team API
Migration guide
2020-08-262021-09-15
V1 Employees.EmployeeRoles Team API
Migration guide
2020-08-262021-09-15
V2 Employees Team API
Migration guide
2020-08-262021-09-15
V2 Transactions Payments API
Migration guide
2019-08-15TBD

Retired Permalink Get a link to this section

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.

V1 Collection
Replacements
Deprecation
Retirement
V1 Employees.Timecards Labor API
Migration guide
2020-02-262021-02-26
V1 Employees.CashDrawers Cash Drawers API
Migration guide
2020-02-262021-02-26
V1Items Catalog API
Inventory API
Migration guide
2019-11-202021-02-26
V1 Locations Locations API
Migration guide
2019-11-202020-11-18
V1 Transactions.BankAccounts Bank Accounts API
Migration guide
2020-02-262021-02-26
V2 Reporting Payments API
Migration guide
2019-08-152020-08-26

Work in progress Permalink Get a link to this section

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

V1 Collection
Replacements
Deprecation
Retirement
V1 Transactions.PaymentspendingTBDTBD
V1 Transactions.RefundspendingTBDTBD
V1 Transactions.SettlementspendingTBDTBD

Deprecated endpoints Permalink Get a link to this section

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.

Endpoint name Replacement Deprecated Retirement
RenewToken OAuth.ObtainToken
Migration guide
2019-03-13 2021-11-17
ListLoyaltyPrograms RetrieveLoyaltyProgram
Migration guide
2021-05-13 2022-05-13
ListEmployeeWages ListTeamMemberWages
Migration guide
2020-08-26 2021-08-26
GetEmployeeWage GetTeamMemberWage
Migration guide
2020-08-26 2021-08-26