Migrate from Connect v1

Connect v1 Retirement

This document provides general information about the Connect v1 retirement effort and links to migration guides for specific v1 APIs.

Current status
Permalink Get a link to this section

V1 Collection Replacements Status Deprecation Retirement
V1Batching Various

Migration guide
Deprecated 2019-11-20 2020-11-18
V1Employees.Employees pending Work in progress TBD TBD
V1Employees.EmployeeRoles pending Work in progress TBD TBD
V1Employees.Timecards pending Work in progress TBD TBD
V1Employees.CashDrawers pending Work in progress TBD TBD
V1Items Catalog API
Inventory API

Migration guide
Deprecated 2019-11-20 2020-11-18
V1Locations Locations API

Migration guide
Deprecated 2019-11-20 2020-11-18
V1Transactions.Payments pending Work in progress TBD TBD
V1Transactions.Refunds pending Work in progress TBD TBD
V1Transactions.Settlements pending Work in progress TBD TBD
V1Transactions.BankAccounts pending Work in progress TBD TBD

Why is Square retiring Connect v1?
Permalink Get a link to this section

The Connect v1 APIs were introduced in 2014. Since then, Square has collected developer feedback and learned more about building robust APIs. The result is an improved Square API data model (previously known as Connect v2) that supports versioning, lays the foundation for a unified development platform, and establishes scalable patterns for future functionality.

Retiring the Connect v1 APIs will allow Square to expand interoperability with first- and third-party products, implement consistent versioning policies, and support regular iteration on functionality in response to developer feedback.

What will happen?
Permalink Get a link to this section

As gaps between the Square API model and Connect v1 are filled, the corresponding Connect v1 APIs will be deprecated. Square strongly recommends against using Connect v1 APIs for new applications. Deprecated endpoints are clearly flagged in the Technical Reference and Square will provide migration guides for affected developers.

Important

Some Connect v1 functionality will not be implemented in Connect v2 due to low usage. Where possible, the applicable migration guide provides an alternative approach.

Who is affected?
Permalink Get a link to this section

Short-term, only developers currently using a deprecated endpoint need to take immediate action. Long-term, anyone using REST or Square SDKs to call the the Connect v1 endpoints listed below will need to update their code as the retirement effort continues.

V1Batching V1SubmitBatch      
V1Employees CreateEmployee
CreateEmployeeRole
CreateTimecard
DeleteTimecard
ListCashDrawerShifts
ListEmployeeRoles
ListEmployees
ListTimecardEvents
ListTimecards
RetrieveCashDrawerShift RetrieveEmployee
RetrieveEmployeeRole
RetrieveTimecard
UpdateEmployee
UpdateEmployeeRole
UpdateTimecard
V1Items AdjustInventory
ApplyFee
ApplyModifierList
CreateCategory
CreateDiscount
CreateFee
CreateItem
CreateModifierList
CreateModifierOption
CreatePage
CreateVariation
DeleteCategory
DeleteDiscount
DeleteFee
DeleteItem
DeleteModifierList
DeleteModifierOption
DeletePage
DeletePageCell
DeleteVariation
ListCategories
ListDiscounts
ListFees
ListInventory
ListItems
ListModifierLists
ListPages
RemoveFee
RemoveModifierList
RetrieveItem
RetrieveModifierList
UpdateCategory
UpdateDiscount
UpdateFee
UpdateItem
UpdateModifierList
UpdateModifierOption
UpdatePage
UpdatePageCell
UpdateVariation
UploadItemImage
V1Locations ListLocations
RetrieveBusiness
     
V1Transactions CreateRefund
ListBankAccounts
ListPayments
ListRefunds
ListSettlements
RetrieveBankAccount
RetrievePayment
RetrieveSettlement
 

When will my code break?
Permalink Get a link to this section

Connect v1 APIs are deprecating as their replacements become publicly available. Once a given API is deprecated, existing users will have 12 months to update their code before the functionality is retired and permanently disabled. For more information about how Square handles API deprecation and retirement, see the Square API Lifecycle overview.

Where can I get help?
Permalink Get a link to this section

If you have questions about Connect v1 retirement or need help migrating to the Square API model, please contact Developer Support, join our Slack, or reach out to your Square Account Manager

How do I update my code?
Permalink Get a link to this section

Consult the relevant migration guides below to update your application.

FAQs
Permalink Get a link to this section

What happens if I call an API after the retired date?
Permalink Get a link to this section

Your code will break.

Retired functionality cannot be used, regardless of the Square-Version provided during the API call. Square SDKs released on or after the retirement date do not include retired features and REST calls that attempt to use retired functionality return errors.