LOCATIONS API

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 Permalink Get a link to this section

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:

  1. Go to the Seller Dashboard.

  2. In the left pane, choose Accounts & Settings.

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

  1. Go to the Developer Dashboard.

  2. Choose one of the applications from the My Applications section.

  3. Choose Locations.

About the main location Permalink Get a link to this section

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.

locations

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 Permalink Get a link to this section

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.

  1. Go to the Developer Dashboard.

  2. Choose an application.

  3. On the application page, you can toggle between the Sandbox and Production account. Choose the Sandbox mode.

  4. Choose Locations in the left navigation. You see a list of locations you can use in Sandbox testing.

API for managing locations Permalink Get a link to this section

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 Permalink Get a link to this section

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.

Create Location
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
  • 17
  • 18
  • 19
  • 20
  • 21
  • 22
  • 23
  • 24
  • 25
  • 26
  • 27
  • 28
  • 29
curl https://connect.squareup.com/v2/locations \
  -X POST \
  -H 'Square-Version: 2021-03-17' \
  -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 Permalink Get a link to this section

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
    • 1
    • 2
    • 3
    • 4
    curl https://connect.squareup.com/v2/locations/{location_id} \
      -H 'Square-Version: 2021-03-17' \
      -H 'Authorization: Bearer {ACCESS_TOKEN}' \
      -H 'Content-Type: application/json'

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

    Retrieve Location
    • 1
    • 2
    • 3
    • 4
    curl https://connect.squareup.com/v2/locations/main \
      -H 'Square-Version: 2021-03-17' \
      -H 'Authorization: Bearer {ACCESS_TOKEN}' \
      -H 'Content-Type: application/json'

Retrieve a list of locations Permalink Get a link to this section

The following ListLocations request retrieves information about all the locations for a seller account identified by the access token in the Authorization header:

List Locations
  • 1
  • 2
  • 3
  • 4
curl https://connect.squareup.com/v2/locations \
  -H 'Square-Version: 2021-03-17' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json'

Update a location Permalink Get a link to this section

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
      • 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-03-17' \
        -H 'Authorization: Bearer {ACCESS_TOKEN}' \
        -H 'Content-Type: application/json' \
        -d '{
          "location": {
            "name": "New Name"
          }
        }'

      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
      • 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-03-17' \
        -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"
            }
          }
        }'
  • 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.

    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 Permalink Get a link to this section

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 Permalink Get a link to this section

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:

Update Location
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
curl https://connect.squareupsandbox.com/v2/locations/{location_id} \
  -X PUT \
  -H 'Square-Version: 2021-03-17' \
  -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 Permalink Get a link to this section

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 Permalink Get a link to this section

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 Permalink Get a link to this section

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:

  1. Go to the Developer Dashboard.

  2. Choose an application.

  3. Choose the Locations tab.

  4. On the Locations page, choose Sandbox.

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