Build Basics

Square API Lifecycle

This document 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 2 API sets:

  • Connect v1 APIs — The original API set released in 2014, 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.

Beta
Permalink Get a link to this section

Beta code is considered stable and production ready but may 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 (e.g., new core functionality, new APIs) are also covered in the Documentation section of the Developer resource site.

General availability (GA)
Permalink Get a link to this section

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 sections of the Developer resource site.

Deprecated
Permalink Get a link to this section

Deprecated functionality remains publicly available but 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

Square strongly encourages existing users to migrate to the applicable replacements as soon as possible to avoid disrupting their users. Developers using Square SDKs release on, or after, the deprecation date will 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 on retired functionality is removed from the Technical Reference and Documentation sections of the Developer resource site. Retired functionality may still appear in archived versions of the Technical Reference, but cannot be accessed, even by applications still pinned to an older Square-Version.

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 date noted below. See the associated migration guide for guidance.

API Name Replacement Deprecated Retirement
v1 Batching API Various
Migration guide
2019-11-20 2020-11-18
v1 Items API Catalog API
Inventory API
Migration guide
2019-11-20 2020-11-18
v1 Locations API Locations API
Migration guide
2019-11-20 2020-11-18
Reporting API Folded into Payment.app_fee_money 2019-08-14 2020-11-18
Transactions API Payments API
Refunds API
Orders API
Migration guide
2019-08-14 2021-09-22

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. See the associated migration guide or relevant Technical Reference entry for guidance.

Endpoint Name Replacement Deprecated Retirement
OAuth.RenewToken OAuth.ObtainToken
Migration guide
2019-03-13 2021-11-17

Deprecated data types and fields
Permalink Get a link to this section

The following types and fields are deprecated and currently scheduled for retirement. See the associated Technical Reference entry for guidance.

Entity Deprecated Retirement
Name: CreateOrderRequestLineItem
Replacement: OrderLineItem
2019-02-13 2020-11-18
Name: CreateOrderRequestTax
Replacement: OrderLineItemTax
2019-02-13 2020-11-18
Name: CreateOrderRequestDiscount
Replacement: OrderLineItemDiscount
2019-02-13 2020-11-18
Name: CreateOrderRequestModifier
Replacement: OrderLineItemModifier
2019-02-13 2020-11-18
Name: InventoryPhysicalCount.status
Replacement: InventoryPhysicalCount.state
2018-09-18 2018-09-18
Name: InventoryCount.status
Replacement: InventoryCount.state
2018-09-18 2018-09-18
Name: InventoryAdjustment.from_status
Replacement: InventoryAdjustment.from_state
2018-09-18 2018-09-18
Name: InventoryAdjustment.to_status
Replacement: InventoryAdjustment.to_state
2018-09-18 2018-09-18
Name: InventoryAdjustment.from_location_id
Replacement: InventoryTransfer.from_location_id
2018-09-18 2018-09-18
Name: InventoryAdjustment.to_location_id
Replacement: InventoryTransfer.to_location_id
2018-09-18 2018-09-18
Name: CatalogPricingRule.apply_products_id
Replacement: CatalogPricingRule.exclude_products_id
2019-09-25 2020-01-22
Name: CreateOrderRequest.reference_id
Replacement: Order.reference_id
2019-02-13 2020-11-18
Name: CreateOrderRequest.line_items
Replacement: Order.line_items
2019-02-13 2020-11-18
Name: CreateOrderRequest.taxes
Replacement: Order.taxes
2019-02-13 2020-11-18
Name: CreateOrderRequest.discounts
Replacement: Order.discounts
2019-02-13 2020-11-18
Name: OrderLineItem.taxes
Replacement: OrderLineItem.applied_taxes
2019-08-14 2020-11-18
Name: OrderServiceCharges.taxes
Replacement: OrderServiceCharge.applied_taxes
2019-08-14 2020-11-18
Name: OrderLineItem.discounts
Replacement: OrderLineItem.applied_discounts
2019-08-14 2020-11-18
Name: OrderReturnLineItem.return_taxes
Replacement: OrderReturnLineItem.applied_taxes
2019-08-14 2020-11-18
Name: OrderReturnLineItem.return_discounts
Replacement: OrderReturnLineItem.applied_discounts
2019-08-14 2020-11-18
Name: OrderReturnServiceCharge.return_taxes
Replacement: OrderReturnServiceCharge.applied_taxes
2019-08-14 2020-11-18