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
If you need help migrating to Square API or need more time to complete your migration, contact Developer Support, join our Discord community, or reach out to your Square account manager..
- 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:
| V1 Locations | Locations | Notes |
|---|---|---|
ListLocations | ListLocations | Returns all locations associated with the Square account. The location ID is the primary identifier for Location objects and is referenced by other Square APIs. |
RetrieveBusiness | ListLocations, ListMerchants, SearchTeamMembers | Mapping depends on the field being migrated from. If multiple fields are used, calls to more than one of these endpoints might be required. You should choose an entity from each list as follows:ListMerchants - There is a single merchant in the list.ListLocations - Choose the location with the oldest created_at that is active.SearchTeamMembers - Choose the team member with is_owner equal to true. |
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.
V1 Merchants field | Location field | Notes |
|---|---|---|
account_capabilities | capabilities, if migrating from v1/me/locations | Value and type unchanged. If you're migrating from v1/me (RetrieveBusiness), this field is removed. |
account_type | REMOVED | This described a legacy account state. |
business_address | address | Value and type unchanged. |
business_name | REMOVED | Use name. |
business_phone | phone_number | Value and type unchanged. |
business_type | mcc | The Square Locations API includes the business type but with a different encoding. Instead of the Square-curated enum from V1Merchant.business_type, the mcc field uses the industry-standard MCC code.If you're migrating from v1/me (RetrieveBusiness), call Locations.ListLocations and choose the location with the oldest created_at value that is active. |
country_code | country | Value and type unchanged. |
currency_code | currency | Value and type unchanged. |
email | See Notes column | You can get the email address of the owner by calling the SearchTeamMembers endpoint and iterating through the results to find the team member with is_owner=true. |
language_code | language_code | Value and type unchanged. |
location_details.nickname | name | V1MerchantLocationDetails fields are now listed directly in the Location object.Location.name must be unique across all locations associated with a given Square account. |
market_url | website_url | V1Merchant.market_url is a link to a form of online store that is being retired and is not represented in the Square Locations API. If you want any web presence for the merchant, use the Location.website_url field. References to the new Square online store are currently not supported. |
name | business_name | Value and type unchanged. The business_name field in the Locations API consolidates the V1Merchant.name and V1Merchant.business_name fields.If you're migrating from v1/me (RetrieveBusiness), you should get business_name from Merchants.ListMerchants. |
shipping_address | REMOVED | Use address.In the v2 Locations API, there is a consolidated address rather than a separate V1Merchant.shipping_address and V1Merchant.business_address. |
To read location information with the Locations API, call ListLocations and search for the correct location:
# Assumes AUTHZ_TOKEN is set to a valid access token for the Square account curl \ -X GET \ -H "Authorization: Bearer ${AUTHZ_TOKEN}" \ -H "Content-Type: application/json" \ https://connect.squareupsandbox.com/v2/locations | json_pp
You can also call RetrieveLocation with a known location ID (${LOCATION_ID}):
# Assumes AUTHZ_TOKEN is set to a valid access token for the Square account # and LOCATION_ID is set to a valid location ID for the Square account curl \ -X GET \ -H "Authorization: Bearer ${AUTHZ_TOKEN}" \ -H "Content-Type: application/json" \ https://connect.squareupsandbox.com/v2/locations/${LOCATION_ID} | json_pp
Did you know?
Location objects include a merchant_id field, which is a unique identifier for the associated Square account. Developers who only care about the merchant ID can choose to use the Merchants API instead of Locations API to reduce the bandwidth requirements of their application. For more information, see the Merchants API guide.
- 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.