Run Business

Locations API Guide

Get information on all the locations for a single merchant account, including location IDs.

The Locations API can pull location details for display on a webpage or access location IDs for locations added after the application was created. Also, most Square API endpoints require a location ID parameter, which can be loaded dynamically with the Locations API instead of saving an explicit location ID as part of the application source code.

Requirements and limitations

  • The Locations API cannot create or edit locations. Locations can only be created in the Square Merchant Dashboard.
  • The Locations API is supported in sandbox, but sandbox locations are predefined and cannot be changed.
  • Applications that use OAuth need the MERCHANT_PROFILE_READ permission.

How to use it — Locations API data model

Locations are a way to organize the different parts of a business under a single Square account. For example, a Square account can different locations to represent each of its physical or virtual storefronts. Every Square account is made with a default location based on the business name and accounts can have multiple locations.

The Locations API works with the following key data types:

  • Location — Represents a location associated with a Square merchant account.
  • LocationsCapabilities — Indicates whether the location can process credit cards.
  • LocationType — Indicates whether the location is PHYSICAL or MOBILE. Mobile locations do not have a physical location.
  • Address — The real-world address of a physical location. The Address object is only relevant for locations with a LocationType of PHYSICAL.
  • LocationStatus — Indicates whether the location is active or inactive.

ListLocation requests require an access token for authentication. Requests can use a personal access token or an OAuth access token returned by the OAuth API.

The ListLocations endpoint returns a list of Location objects. Note that the id field of Location objects correspond to the location_id parameter required by most Square API endpoints.

How it works — Locations API process flow

High level process overview

  1. The application backend calls ListLocations with a valid access token.
  2. Square returns a list of locations with location_ids for the Square account associated with the access token.
  3. The backend extracts the location_id and saves it.
  4. The location ID can now be used to make API calls that require a location.
Process flow

Locations API Setup

Working Example

Our sample code has the following characteristics. These characteristics are not required to use the Locations API.

  • This sample code uses REST API calls written in Python version 2. But, you can communicate with Square API endpoints using any programming language.
  • This example uses a sandbox token. While we recommend using OAuth for authorization whenever possible in production, OAuth is not currently supported in sandbox and unscoped tokens (sandbox tokens, personal access tokens) provide an easy way to get started quickly.

Step 1: Get your application credentials

We recommend using your sandbox token and locations for testing and development. To get your sandbox ID:

  1. Open your Application Dashboard.
  2. If you DO have an application you want to use for accepting online payments, click on the application.
  3. If you DO NOT have an application you want to use for accepting online payments, click New Application, enter a name for your application (e.g., "My Online Store") and click Create Application.
  4. Copy the Sandbox Access Token value on the Credentials tab of the application control panel.

Step 2: Create a simple ListLocations request

  1. Create a new blank text file calledß listlocations.py.
  2. In your new file, import the HTTP client library and set your sandbox token as your access token. Be sure to replace REPLACE_ME with your sandbox token.
#!/usr/bin/python
import httplib, json

accessToken = 'REPLACE_ME'
  1. Send a GET request to the ListLocations endpoint and obtain the response.
# Set your request headers.
request_headers = {'Authorization': 'Bearer ' + accessToken,
                   'Accept':        'application/json',
                   'Content-Type':  'application/json'}

request_path = '/v2/locations'
request_body = ''

connection = httplib.HTTPSConnection('connect.squareup.com')
connection.request('GET', request_path, request_body, request_headers)
response = connection.getresponse()
  1. Convert the returned JSON body into an array of locations to help make it easier to work with and print it to the screen.
#Convert response to JSON and store it in a variable.
locations = json.loads(response.read())

# Pretty-print the locations array.
print json.dumps(locations, indent=2, separators=(',',': '))

The sample code above prints the raw response for testing purposes.

Step 3: Test your code

Run your sample code with the Python interpreter to print the JSON output to the command line in the Mac Terminal or Windows Command Prompt.

python listlocations.py

You should receive a list of Location objects for all the locations you have in your account.

Next
Locations API Reference >

Contact Developer Support, join our Slack channel, or ask for help on Stack Overflow