Connect v1 Migration

Migrate from Connect v1 Locations API

The information below will help you migrate from the Connect v1 Locations API to the correct Square API counterparts. For general guidance on the differences between Connect v1 and Square APIs, see the Connect v1 Migration guide.

Catalog API
Inventory API
cURL (Command Line)

What you need to know
Permalink Get a link to this section

The Connect v1Locations API let developers read business details for a Square account but business information still had to be managed through Square Dashboard or Square Point of Sale. The Square API replacement, also named Locations API, supports reading and writing of business information for Square accounts.

Important dates
Permalink Get a link to this section

  • Deprecation: 2019-11-20

  • Retirement: 2020-11-18

Get help
Permalink Get a link to this section

If you need help migrating to Square API or need more time to complete your migration, please contact Developer Support, join our Slack, or reach out to your Square Account Manager.

General behavioral differences
Permalink Get a link to this section

  • Information is location-based — Square APIs differentiate between account-level information and location-level information. Account-level information includes the business name, merchant ID, and MCC. All other information is specific to a given location and can be updated without changing the details associated with other locations.

  • 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. See the Locations object entry in the Square Technical Reference for more information.

  • Locations are writeable — The v1Locations API is a read-only API. Square Locations API supports reading, creating, and updating Location information.

Endpoint mapping
Permalink Get a link to this section

Code relying on the following endpoints must be updated to avoid breaking when the v1 Locations API reaches retirement:

v1Locations Locations Notes
ListLocations ListLocations Returns all locations associated with the Square account.

Location ID is the primary identifier for Location objects and is referenced by other Square APIs. To find the ID of a given location, you can present a list of locations in your UI or search on Location.name in the result set. Note: While location names must be unique within a Square account, name is a writeable field and may change over time.
RetrieveBusiness RetrieveLocation Unlike RetrieveBusiness, the RetrieveLocation endpoint requires a valid location ID as input. Developers who do not know the desired ID in advance should use ListLocations.

Example migration
Permalink Get a link to this section

With 2 exceptions, all fields in V1Merchant objects are also available in Square API Location objects. As a result, most code will only need to update the endpoint reference and field names to work properly.

V1Merchant field Location field Notes
id id V1Merchant.id corresponds to Location.id. The object IDs are stable between the v1Locations API and the Locations API.
account_capabilities capabilities Value and type unchanged.
account_type type Value and type unchanged.
business_address address Value and type unchanged.
business_name REMOVED Use name.

V1Merchant.business_name was removed because it duplicated the information in V1Merchant.name.
business_phone phone_number Value and type unchanged.
business_type mcc Most developers will not need this field.

V1Merchant.business_type is a Square-defined string representing the commercial purpose of the associated Square account (e.g., bookstore, gym). The Square Locations API does away with custom strings in favor of a standardized 4-digit, MCC code that is also recognized by credit card processors.
country_code country Value and type unchanged.
currency_code currency Value and type unchanged.
email business_email Value and type unchanged.
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 worked with the old Square Online Store product. Developers who need to preserve Online Store URLs should port the URL to the Location.website_url field.
name business_name Value and type unchanged.
shipping_address REMOVED Use address.

V1Merchant.shipping_address was removed because it did not work as intended. The shipping address was set during Square account creation and remained read-only from that point forward even for the account owner.

To read location information with Locations API, call ListLocations and search for the right 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

or 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, a unique identifier for the associated Square account. Developers that only care about merchant ID may choose to use the Merchants API instead of Locations API to reduce the bandwidth requirements of their app. See the Merchants API guide for more information.

Common migration pitfalls
Permalink Get a link to this section

  • Location IDs matter now — Location IDs are available, but mostly unused by the v1Locations API. 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.