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.

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:

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 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:

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 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.

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.

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

• Retrieve a specific location

• Retrieve a list of locations

• Update a location

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.

curl https://connect.squareup.com/v2/locations \
  -X POST \
  -H 'Square-Version: 2021-09-15' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "location": {
      "name": "new location",
      "description": "created using CreateLocation endpoint",
      "address": {
        "address_line_1": "1234 1st street",
        "administrative_district_level_1": "GA",
        "locality": "Atlanta",
        "postal_code": "30309"
      },
      "twitter_username": "twitter",
      "instagram_username": "instagram",
      "facebook_url": "facebook.com/facebookurl",
      "business_hours": {
        "periods": [
          {
            "day_of_week": "MON",
            "start_local_time": "01:02",
            "end_local_time": "02:03"
          }
        ]
      }
    }
  }'

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.

  Retrieve Location

  cURL

  • cURL
  • C#
  • Java
  • PHP
  • Python
  • Ruby
  • Node.js

  Copy

  • 1
  • 2
  • 3
  • 4

  curl https://connect.squareup.com/v2/locations/{location_id} \
    -H 'Square-Version: 2021-09-15' \
    -H 'Authorization: Bearer {ACCESS_TOKEN}' \
    -H 'Content-Type: application/json'

  Try in API Explorer

  The following is an example response:

  Copy

  {
    "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 specifies main as the location ID to retrieve the main location information:

  Retrieve Location

  cURL

  • cURL
  • C#
  • Java
  • PHP
  • Python
  • Ruby
  • Node.js

  Copy

  • 1
  • 2
  • 3
  • 4

  curl https://connect.squareup.com/v2/locations/main \
    -H 'Square-Version: 2021-09-15' \
    -H 'Authorization: Bearer {ACCESS_TOKEN}' \
    -H 'Content-Type: application/json'

  Try in API Explorer

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:

curl https://connect.squareup.com/v2/locations \
  -H 'Square-Version: 2021-09-15' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json'

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.

    Update Location

    cURL

    • cURL
    • C#
    • Java
    • PHP
    • Python
    • Ruby
    • Node.js

    Copy

    • 1
    • 2
    • 3
    • 4
    • 5
    • 6
    • 7
    • 8
    • 9
    • 10

    curl https://connect.squareup.com/v2/locations/{location_id} \
      -X PUT \
      -H 'Square-Version: 2021-09-15' \
      -H 'Authorization: Bearer {ACCESS_TOKEN}' \
      -H 'Content-Type: application/json' \
      -d '{
        "location": {
          "name": "New Name"
        }
      }'

    Try in API Explorer

    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.

    Update Location

    cURL

    • cURL
    • C#
    • Java
    • PHP
    • Python
    • Ruby
    • Node.js

    Copy

    • 1
    • 2
    • 3
    • 4
    • 5
    • 6
    • 7
    • 8
    • 9
    • 10
    • 11
    • 12
    • 13
    • 14
    • 15
    • 16

    curl https://connect.squareup.com/v2/locations/{location_id} \
      -X PUT \
      -H 'Square-Version: 2021-09-15' \
      -H 'Authorization: Bearer {ACCESS_TOKEN}' \
      -H 'Content-Type: application/json' \
      -d '{
        "location": {
          "address": {
            "address_line_1": "123 My street",
            "locality": "SEATTLE",
            "administrative_district_level_1": "WA",
            "postal_code": "98007-5059",
            "country": "US"
          }
        }
      }'

    Try in API Explorer

• Clear location fields. If you want to set an existing field value to null, you must include the X-Clear-Null header. Otherwise, the request succeeds but the value is not cleared. In the following example, you set the description field to null. The request specifies the X-Clear-Null header.

  Copy

  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 the following webhook events:

For more information about using webhooks, see Webhooks Overview. For a list of webhook events you can subscribe to, see V2 Webhook Events Reference.

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:

• USDA MCC directory.

• Visa Merchant Data Standards Manual.

• Mastercard Quick Reference.

• Citibank MCC list.

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.

The following example sets MCC 8299 for a location:

curl https://connect.squareupsandbox.com/v2/locations/{location_id} \
  -X PUT \
  -H 'Square-Version: 2021-09-15' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -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:

After the MCC is reset, you can call UpdateLocation and set a location's MCC again.

Location language code

Each seller's location has a language_code associated with it. The language_code can be one of the following Square-supported language codes for the country where the location exists:

• Australia. en-AU

• Canada. fr-CA, en-CA

• France. en, fr

• Ireland. en-IE

• Japan. en, ja

• United Kingdom. en-GB

• United States. en-US, es-US

• All other countries. en, es, fr, ja

These language codes are a subset of the language tags described in RFC 5646. Each language code identifies a particular language. For example:

• en-US designates American English.

• fr-CA is for Canadian French.

The language code has a primary language, such as "en", followed by an optional dialect subtag such as "US". If a language code has both parts, the parts are separated by a hyphen, for example "en-US".

Location-specific and seller-level language preferences

People communicate with software through natural languages such as English, French, and Spanish. Because each person has a different preferred language, it is important for applications to track and accommodate individual language preferences. Square maintains seller-level and location-specific language preferences. For more information about how applications might choose a language from the available options, see Language Preferences for Applications to Communicate.