Locations API Overview

This section explains what locations are in a seller account and how to manage them using the Locations API and the Square dashboards.

When a seller signs up to create a Square account, among other things, the seller provides 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 that the business is located at. For mobile locations, it is the official address of the business used for legal purposes and to process payments.

Square stores some of 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. 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 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 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 will need a location ID as you explore these APIs. So, for convenience, the location information is also available on the developer dashboard:

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 Testing Square APIs With Sandbox.

When testing the API, developers will need a location for the v2 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's 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 dashboard) is the only required field. For the following location fields, unless you explicitly provide values, Square uses existing location data to populate these fields:

• business_name (set to the name field value provided in the request)

• address

• capabilities

• status

• merchant_id

• country

• language_code

• currency

• mcc

For non-read-only fields, if you don't 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 as shown. In the request:

• The request provides a location ID in the request URL.

• The Authorization header provides the access token of the seller account.

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:

{
   "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"
            }
         ]
      }
   }
}

Retrieve a list of locations

The following ListLocations request retrieves information of all 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 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 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 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

  • Bearer token in the Authorization header provides 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 an existing field value to null, you must include the X-Clear-Null header. Otherwise, the request will succeed but the value will not be 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}}'