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 Alpha, to Beta, to General Availability (GA) before Deprecation and Retirement. Deprecated functionality typically remains publicly available for 12 months before Square retires the functionality.

Release states Permalink Get a link to this section

Beta Permalink Get a link to this section

Beta code is considered stable and production ready but might not have all the functionality intended for final release. 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

General Availability (GA) code is considered stable, polished, and production ready. 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

Deprecated functionality remains publicly available but its use is strongly discouraged for all applications, regardless of the Square-Version provided during API calls. Deprecated functionality is clearly tagged in the Documentation section and grouped together in the Technical Reference section of the Developer resource site. Deprecated APIs typically provide a 12-month support period before permanent retirement.

Important

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

Retired Permalink Get a link to this section

Retired code is unavailable to all applications regardless of the Square-Version provided during 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. Retired functionality might still appear in archived versions of the Technical Reference, but cannot be accessed, even by applications still pinned to an older Square-Version.

Retirement timeline Permalink Get a link to this section

Deprecated APIs Permalink Get a link to this section

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

V1 Collection
Replacements
Status
Deprecation
Retirement
V1 BatchingVarious
Migration guide
Deprecated2019-11-202020-11-18
V1 Employees.Employees Team API
Migration guide
Deprecated2020-08-262021-08-26
V1 Employees.EmployeeRoles Team API
Migration guide
Deprecated2020-08-262021-08-26
V1 Employees.Timecards Labor API
Migration guide
Deprecated2020-02-262021-02-26
V1 Employees.CashDrawers Cash Drawers API
Migration guide
Deprecated2020-02-262021-02-26
V1Items Catalog API
Inventory API
Migration guide
Deprecated2019-11-202020-11-18
V1 Locations Locations API
Migration guide
Deprecated2019-11-202021-05-18
V1 Transactions.PaymentspendingWork in progressTBDTBD
V1 Transactions.RefundspendingWork in progressTBDTBD
V1 Transactions.SettlementspendingWork in progressTBDTBD
V1 Transactions.BankAccounts Bank Accounts API
Migration guide
Deprecated2020-02-262021-02-26
V2 Employees Team API
Migration guide
Deprecated2020-08-262021-08-26
V2 Transactions Payments API
Migration guide
Deprecated2019-08-152021-09-01
V2 Reporting Payments API
Migration guide
Retired2019-08-152020-08-26

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
ListEmployeeWages ListTeamMemberWages
Migration guide
2020-08-26 2021-08-26
GetEmployeeWage GetTeamMemberWage
Migration guide
2020-08-26 2021-08-26

Deprecated fields Permalink Get a link to this section

The following fields are deprecated and replaced: