Locations API
This topic explains what locations are in a seller account and how to manage them using the Locations API and the Square dashboards.
On this page
Overview
When a seller signs up to create a Square account, the seller provides core business profile information such as:
Business name. The name of the business as it is known by anyone who interacts with the business. Square prints the name on receipts, shares it with government tax agencies, reports it on credit card statements, and shows it on the Square Point of Sale application.
Location type. Whether the location is a fixed physical location (for example, a restaurant) or is a mobile location (for example, a food truck).
Phone number. A phone number that is optionally shared with customers.
Business address. The address of the business. For physical locations, it is the address where the business is located. For mobile locations, it is the official address of the business used for legal purposes and to process payments.
Square stores this information by creating a Location
object. You can review and edit the location information on the Seller Dashboard:
Go to the Seller Dashboard.
In the left pane, choose Accounts & Settings.
On the Accounts & Settings page, choose Locations from the Business drop-down list in the left pane.
You see one location for the newly created account. This is also referred to as the main location. You can choose the location to get more information.
A business, such as a fast food chain, can have multiple locations. Accordingly, you can create additional locations in the Seller Dashboard. Each location has a Square-assigned location ID.
Several of the Square API operations are location specific. You must include a location ID in the API endpoint request. For example:
When you send a
CreateOrder
request, you must specify a location ID in the endpoint URL to specify where the transaction occurred.When you send a
ListEmployees
request, you can optionally specify a location ID to retrieve a list employees at a specific location.When you take a payment using the
CreatePayment
API, there is a location associated with the payment.
If you are a developer, you need a location ID as you explore these APIs. The location information is also available on the Developer Dashboard:
Go to the Developer Dashboard.
Choose one of the applications from the My Applications section.
Choose Locations.
About the main location
When you sign up to create a Square account, the initial location Square creates is referred to as the main location or the default location. The following applies to the main location:
The Square Seller Dashboard and some APIs, such as the
CreatePayment
endpoint, refer to a default location, which is the same as the main location.If you deactivate the main location, Square chooses a new main location from the remaining list of active locations.
Locations for use in Sandbox testing
Your Square seller account has a Sandbox account that you can use for API testing. For more information, see Test in the Sandbox.
When testing the API, developers need a location for the Sandbox environment. Square provides a location for use in the Sandbox environment.
Go to the Developer Dashboard.
Choose an application.
On the application page, you can toggle between the Sandbox and Production account. Choose the Sandbox mode.
Choose Locations in the left navigation. You see a list of locations you can use in Sandbox testing.
API for managing locations
The Locations API provides a set of endpoints that you can use to manage seller locations. The following are some example cURL commands:
Create a location
You can add a new business location using the Square Seller Dashboard or programmatically using the CreateLocation endpoint. The location name
(referred to as the Nickname in Seller Dashboard) is the only required field. A location name must be unique within a seller account. For the following location fields, unless you explicitly provide values, Square uses existing main location data to populate these fields:
business_name
address
capabilities
status
merchant_id
country
language_code
currency
mcc
For non-read-only fields, if you do not want Square to set these field values, you have the option of setting the field values to null
. In this case, you must include the X-Clear-Null
header in the request with value true
.
For information about these location fields, see the Location type.
Each seller account can have up to 300 business locations. The following is an example CreateLocation
request. In the request, the Authorization
header provides the access token of the seller account where you want to create the location.
The following is an example response:
{
"location":{
"id":"LOCATION_ID",
"name":"new location",
"address":{
"address_line_1":"1234 1st street",
"locality":"Atlanta",
"administrative_district_level_1":"GA",
"postal_code":"30309"
},
"capabilities":[
"CREDIT_CARD_PROCESSING"
],
"status":"ACTIVE",
"created_at":"2019-11-09T22:00:19Z",
"merchant_id":"MERCHANT_ID",
"country":"US",
"language_code":"en-US",
"currency":"USD",
"business_name":"loc 100-nickname",
"type":"PHYSICAL",
"business_hours":{
"periods":[
{
"day_of_week":"MON",
"start_local_time":"01:02",
"end_local_time":"02:03"
}
]
},
"description":"created using CreateLocation endpoint",
"twitter_username":"twitter",
"instagram_username":"instagram",
"facebook_url":"facebook.com/facebookurl",
"mcc":"7299"
}
}
Retrieve a specific location
If you know a location ID, you can retrieve the specific location information using the RetrieveLocation endpoint. This endpoint also supports specifying main
as the location ID, in which case it returns information about the first location created when the seller account was created.
The following example request:
Specifies a location ID in the request URL.
Specifies the access token of the seller account in the
Authorization
header.The following is an example response:
{ "location": { "id": "7WQ0KXC8ZSD90", "name": "location-xyz", "address": { "address_line_1": "111 Maple NE", "locality": "Seattle", "administrative_district_level_1": "WA", "postal_code": "98001-5059", "country": "US" }, "timezone": "America/Los_Angeles", "capabilities": [ "CREDIT_CARD_PROCESSING" ], "status": "ACTIVE", "created_at": "2019-01-16T22:20:13Z", "merchant_id": "2RNAQEFCTQ18Y", "country": "US", "language_code": "en-US", "currency": "USD", "business_name": "XYZ corporation", "type": "PHYSICAL", "business_hours": {}, "coordinates": { "latitude": 21.614692, "longitude": -122.138382 }, "logo_url": "https://<Framed-Logo-URL>", "mcc": "7299", "full_format_logo_url": "https://<Full-Logo-URL>" } }
You can also request the main location without knowing its ID. The following
RetrieveLocation
request specifiesmain
as the location ID to retrieve the main location information:
Retrieve a list of locations
The following ListLocations request retrieves information about all the locations for a seller account identified by the access token in the Authorization
header:
Update a location
You use the UpdateLocation endpoint to update one or more location field values. In the request, you provide only the fields you want to update as shown in the following example:
Update a location name. The following
UpdateLocation
request updates the location name. In the request:The location ID in the request URL identifies the location to update.
The bearer token in the
Authorization
header provides the access token of a seller account whose location is being updated.Square returns the updated location object in the response.
Update a location address. The location Address is a composite data type. In this case, even if you want to update a portion of an address, you must include the entire address in the request. The following example updates the address by passing its fields as a nested JSON object. In the request:
The location ID in the request URL identifies the location to update.
The bearer token in the
Authorization
header provides the access token of a seller account whose location is being updated.
Clear location fields. If you want to set an existing field value to
null
, you must include theX-Clear-Null
header. Otherwise, the request succeeds but the value is not cleared. In the following example, you set thedescription
field tonull
. The request specifies theX-Clear-Null
header.curl -X PUT \ -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \ -H "Content-type: application/json" \ -H 'X-Clear-Null: true' -d '{ "location":{ "description": null } }' \ 'https://connect.squareup.com/v2/locations/LOCATION_ID'
Webhooks
The Locations API supports webhook notifications. For a list of subscription events you can subscribe to, see Subscribe to Events.
Initialize a merchant category code
Each seller location has a merchant category code (MCC) that describes the types of goods or services sold at that location. The MCC values are standardized by ISO 18245 and are widely used in the financial industry. Some of the sites that provide MCC descriptions are:
It is helpful to assign an MCC that is closely associated with what the business does at that location. For example:
Credit card issuers use MCCs to identify the type of business the merchant is engaged in and offer points for qualified credit card purchases.
Some payment cards are only accepted by certain types of businesses. For example, HSA cards (limited to medical expenses) or virtual cards from a hotel website (limited to hotel reservations). Such methods are enabled only when sellers have an appropriate MCC.
Applications can connect a seller with customers who are suited for the business by setting categories (for example, a Facebook page category or a Google business category). This approach is more effective when an MCC matches what the business does.
In the context of MCC initialization, Square refers to an MCC as a "specific MCC" if it accurately describes what a business does at a location. In contrast, some MCCs are general purpose and have catch-all descriptions. The Locations API considers the following MCCs as general purpose:
8999 (Professional Services)
7299 (Personal Services)
5944 (Other)
If your business location has any of these general-purpose MCC values, you can call UpdateLocation
to update the MCC to a value that accurately reflects your business.
Important
In the current implementation, after you change the MCC for a location from a general-purpose MCC to a specific MCC, you cannot make further updates to the MCC through this endpoint. However, during testing you can reset a location's MCC to its default value in the Square Sandbox. For more information, see Testing MCC initialization.
The following example sets MCC 8299 for a location:
curl https://connect.squaresandbox.com/v2/locations/LOCATION_ID \
-X PUT \
-H 'Square-Version: 2020-09-23' \
-H 'Authorization: Bearer ACCESS_CODE' \
-H 'Content-Type: application/json' \
-d '{
"location": {
"mcc": "8299"
}
}'
When you create a seller account, Square assigns one of the preceding general-purpose MCC values to the main location (see about main location): 5944 for a seller account in Japan and 7299 for a seller account in other countries.
MCCs available for initialization
You can provide the following MCC values to the UpdateLocation
endpoint:
MCCs available in the United States. 0742, 1520, 4121, 4722, 5399, 5411, 5499, 5699, 5712, 5811, 5812, 5813, 5814, 5944, 5971, 6300, 6513, 7216, 7230, 7298, 7299, 7372, 7392, 7399, 7699, 7997, 8011, 8021, 8111, 8299, 8398, 8651, 8661, 8699, 8931, 8999
MCCs available in Japan. 0742, 1520, 4121, 4722, 5499, 5611, 5712, 5812, 5944, 5971, 5999, 6513, 7230, 7278, 7299, 7361, 7372, 7392, 7699, 7922, 7997, 8021, 8111, 8244, 8398, 8699, 8931, 8999
MCCs available in Canada. 0742, 1520, 4121, 5399, 5499, 5699, 5712, 5811, 5812, 5813, 5814, 5944, 5971, 6300, 6513, 7230, 7299, 7372, 7392, 7399, 7699, 8011, 8021, 8111, 8299, 8398, 8699, 8931, 8999
MCCs available in all other countries. 0742, 1520, 4121, 4722, 5399, 5499, 5699, 5712, 5811, 5812, 5813, 5814, 5944, 5971, 6300, 6513, 7230, 7299, 7372, 7392, 7399, 7699, 8011, 8021, 8111, 8299, 8398, 8651, 8699, 8931, 8999
MCC descriptions
The following are descriptions of the MCCs available for initialization:
0742 - Veterinary
1520 - Trade Contractor
4121 - Taxi/Limo
4722 - Tourism
5399 - Misc. General Merchandise
5411 - Grocery / Market
5499 - Food / Grocery
5611 - Men's Apparel
5699 - Apparel
5712 - Furniture / Home Goods
5811 - Caterers
5812 - Restaurant/Bar
5813 - Bar / Club / Lounge
5814 - Food Truck / Cart
5944 - Jewelry and Watches
5944 - Other (Japan only)
5971 - Art Dealer
5999 - Miscellaneous and Specialty Retail Shops
6300 - Insurance Sales, Underwriting, and Premiums
6513 - Real Estate
7216 - Dry Cleaning and Laundry
7230 - Beauty / Barber
7278 - Outdoor Markets
7298 - Health and Beauty Spas
7299 - Personal Services
7372 - Web Dev/Design
7361 - Tutoring
7392 - Consultant
7399 - Business Services
7699 - Repair Services
7922 - Ticket Sales
7997 - Membership Clubs / Sports Facilities
8011 - Medical Practitioner
8021 - Dentistry
8111 - Legal Services
8244 - Education
8299 - School & Education
8398 - Charity / Social Services
8651 - Political Organizations
8661 - Religious Organizations
8699 - Membership Org
8931 - Accounting
8999 - Professional Services
Testing MCC initialization
In production, you can initialize a location's MCC only once using the UpdateLocation
endpoint. However, you can reset a location's MCC to its default value in the Square Sandbox. This lets you initialize a location's MCC any number of times in the Sandbox for testing purposes. To reset a location's MCC, do the following:
Go to the Developer Dashboard.
Choose an application.
Choose the Locations tab.
On the Locations page, choose Sandbox.
Choose ... (ellipsis) in the Action column next to the location you want to update, and then choose Reset MCC.
After the MCC is reset, you can call UpdateLocation
and set a location's MCC again.