Square API Lifecycle
This topic outlines the lifecycle for Square APIs and establishes expectations for the various stages of development.
On this page
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
API is available. Minor changes can be expected between Beta and 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 may 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
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. Subject to published 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 and limited or no new functionality. Subject to published GA SLA.
APIs are Deprecated as the first stage toward retirement; they will typically be 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 on 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 will move to the Maintenance state when the replacement reaches GA and remain in maintenance for at least six months. If no replacement is planned, the deprecated API will 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 release 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
Critical fixes only. Subject to published GA SLA
APIs in Maintenance will adhere to the same rules as Deprecated APIs but with more limited updates; only critical fixes will be made during this time.
Retired
No support from Square
Retired APIs are no longer available or supported; 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 may 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 will 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.
V1 Collection | Replacements | Deprecation | Retirement |
---|---|---|---|
V1 Batching | Various Migration guide | 2019-11-20 | 2021-09-15 |
V1 Employees.Employees | Team API Migration guide | 2020-08-26 | 2021-09-15 |
V1 Employees.EmployeeRoles | Team API Migration guide | 2020-08-26 | 2021-09-15 |
V2 Employees | Team API Migration guide | 2020-08-26 | 2021-09-15 |
V2 Transactions | Payments API Migration guide | 2019-08-15 | TBD |
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.
V1 Collection | Replacements | Deprecation | Retirement |
---|---|---|---|
V1 Employees.Timecards | Labor API Migration guide | 2020-02-26 | 2021-02-26 |
V1 Employees.CashDrawers | Cash Drawers API Migration guide | 2020-02-26 | 2021-02-26 |
V1Items | Catalog API Inventory API Migration guide | 2019-11-20 | 2021-02-26 |
V1 Locations | Locations API Migration guide | 2019-11-20 | 2020-11-18 |
V1 Transactions.BankAccounts | Bank Accounts API Migration guide | 2020-02-26 | 2021-02-26 |
V2 Reporting | Payments API Migration guide | 2019-08-15 | 2020-08-26 |
Work in progress
The following endpoints will be deprecated when corresponding functionality is available in the Square API.
V1 Collection | Replacements | Deprecation | Retirement |
---|---|---|---|
V1 Transactions.Payments | pending | TBD | TBD |
V1 Transactions.Refunds | pending | TBD | TBD |
V1 Transactions.Settlements | pending | TBD | TBD |
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.
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
The following fields are deprecated and replaced:
Field name | Replacement | Deprecated | Retirement |
CreateOrderRequest.reference_id | Order.reference_id | 2018-07-12 | 2020-11-18 |
CreateOrderRequest.line_items | Order.line_items | 2018-07-12 | 2020-11-18 |
CreateOrderRequest.taxes | Order.taxes | 2018-07-12 | 2020-11-18 |
CreateOrderRequest.discounts | Order.discounts | 2018-07-12 | 2020-11-18 |
Customer.groups |
Customer.group_ids Customer.segment_ids |
2020-04-22 | TBD |
InvoicePaymentRequest.request_method |
Invoice.delivery_method InvoicePaymentRequest.automatic_payment_source (see migration notes) |
2021-01-21 | TBD |
LoyaltyProgramRewardTier.definition | LoyaltyProgramRewardTier.pricing_rule_definition | 2020-12-16 | TBD |
OrderLineItem.taxes | OrderLineItem.applied_taxes | 2018-07-12 | 2020-11-18 |
OrderLineItem.discounts | OrderLineItem.applied_discounts | 2018-07-12 | 2020-11-18 |
Shift.employee_id | Shift.team_member_id | 2020-08-28 | 2021-08-26 |
ShiftFilter.employee_ids | ShiftFilter.team_member_ids | 2020-08-28 | 2021-08-26 |