The following information helps you migrate from the Connect v1 Locations API code to the correct Square API counterparts. For general guidance about the differences between Connect v1 and Square APIs, see the Connect v1 Migration guide.
Migrate from the Connect v1 Locations API
The Connect v1 Locations API lets you read business details for a Square account but business information is still managed through the Square Seller Dashboard or Square Point of Sale. The Square API replacement, called the Locations API, supports reading and writing of business information for Square accounts.
- Deprecation: 2019-11-20
- Retirement: 2020-11-18
- Information is location-based - Square APIs differentiate between account-level information and location-level information. Account-level information includes the business name, seller ID, and preferred language. All other information is specific to a given location and can be updated without changing the details associated with other locations. If you are integrating with /v1/me for one of these fields from the v1 Merchants API, it is important to use /v2/locations and select a specific location. A common rule is to select the location that has the earliest
created_atdate and is active.
- Expanded information set - The Square Locations API provides a broader set of information than the v1 Locations API, including business hours, logo URL, status, and social media accounts for each location. For more information. see the Locations object.
- Locations are writeable. The v1 Locations API is a read-only API. The Square Locations API supports reading, creating, and updating location information.
Code relying on the following endpoints must be updated to avoid breaking when the v1 Locations API reaches retirement:
With two exceptions, all fields in V1 Merchants objects are also available in Square API
Location objects. As a result, most code only needs to update the endpoint reference and field names to work properly.
To read location information with the Locations API, call
ListLocations and search for the correct location:
You can also call
RetrieveLocation with a known location ID (
- Location IDs matter now. In the Square Locations API, even though location names must be unique, valid IDs are required to search and update location information. Developers building integrations with other systems must preserve Square-assigned location IDs in the third-party system to ensure information is synced correctly.