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.

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:

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.

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. 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 -X POST \
-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"
            }
         ]
      }
   }
}' \
'https://connect.squareup.com/v2/locations'

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.

  Copy

  curl -X GET \
  -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
  -H "Content-type: application/json" \
  'https://connect.squareup.com/v2/locations/{{LOCATION_ID}}'
  

  The following is an example response:

  Copy

  {
     "location":{
        "id":"X9XWRESTK1CZ1",
        "name":"location name",
        "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-02-12T23:59:19Z",
        "merchant_id":"BS20H4A5M503E",
        "country":"US",
        "language_code":"en-US",
        "currency":"USD",
        "business_name":"business name",
        "type":"PHYSICAL",
        "business_hours":{
           "periods":[
              {
                 "day_of_week":"MON",
                 "start_local_time":"08:00:00",
                 "end_local_time":"17:00:00"
              },
              {
                 "day_of_week":"WED",
                 "start_local_time":"07:00:00",
                 "end_local_time":"21:00:00"
              }
           ]
        }
     }
  }
  

  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:

  Copy

  curl -X GET \
  -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
  -H "Content-type: application/json" \
  'https://connect.squareup.com/v2/locations/main'
  

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 -X GET \
-H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
-H "Content-type: application/json" \
'https://connect.squareup.com/v2/locations'

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.

    Copy

    curl -X PUT \
    -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
    -H "Content-type: application/json" \
    -d '{
       "location":{
          "Name":"new name"
       }
    }' \
    'https://connect.squareup.com/v2/locations/{{LOCATION_ID}}'
    

    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.

    Copy

    curl -X PUT \
    -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"
             }
       }
    }' \
    'https://connect.squareup.com/v2/locations/{{LOCATION_ID}}'
    

• 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}}'