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.
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
CreateOrderrequest, you must specify a location ID in the endpoint URL to specify where the transaction occurred.When you send a
ListEmployeesrequest, you can optionally specify a location ID to retrieve a list employees at a specific location.When you take a payment using the
CreatePaymentAPI, 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 a seller signs up to create a Square account, the initial location that 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
CreatePaymentendpoint, 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.
A business can have multiple locations. Each location has a Square-assigned location ID. For example, the account associated with Raphael's Puppy-Care Emporium has nine locations:
Three brick and mortar locations with physical addresses in San Diego, San Francisco, and Boston.
Three mobile locations for "treatmobiles" that sell homemade treats and dog toys around Oakland, Chicago, and New York City.
One location for a fleet of pop-up grooming stations that rotate around local dog parks in various cities.
Two virtual locations for an online store and a mobile application. The eCommerce site and mobile application both allow customers to buy products or book appointments for grooming services.
Establishing multiple locations for an account is optional, but potentially useful for reporting and tracking sales over time. Most customer-related interactions (such as taking payments, issuing refunds, and managing inventory) must be attributed to a specific location in the API call.
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_nameaddresscapabilitiesstatusmerchant_idcountrylanguage_codecurrencymcc
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
Authorizationheader.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
RetrieveLocationrequest specifiesmainas 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
UpdateLocationrequest updates the location name. In the request:The location ID in the request URL identifies the location to update.
The bearer token in the
Authorizationheader 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
Authorizationheader 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-Nullheader. Otherwise, the request succeeds but the value is not cleared. In the following example, you set thedescriptionfield tonull. The request specifies theX-Clear-Nullheader.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:
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.