Manage locations

If your Terminal deployment uses many readers across multiple physical locations, keeping track of them all can get overwhelming. Locations help you manage readers and their activity by associating them with a physical operating site. They also ensure your readers download the proper regional configurations.

Use the Terminal Locations object to group readers, view their connectivity status, and customize their settings by physical location. This can be especially helpful for marketplaces with many connected accounts.

After creating Locations, you can use them to help you group readers, improve reader discovery flows, customize their settings by physical location, and more.

Create a location Server-side Dashboard

Create a Location for each physical location that your readers operate at. If your business requires you to move your readers frequently, your locations may use addresses that represent a primary place of business.

To create a new location using the API, use the create location request.

curl https://api.stripe.com/v1/terminal/locations \
  -u 
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -d "display_name"="HQ" \
  -d "address[line1]"="1272 Valencia Street" \
  -d "address[city]"="San Francisco" \
  -d "address[state]"="CA" \
  -d "address[country]"="US" \
  -d "address[postal_code]"="94110" \

A Location’s required address properties differ based on country:

Create a location with Standard Connect

In order to create a location for a Standard Connect Account, use the Stripe-Account header in your request. These locations are only accessible by the Connect account you authenticate as. You can create multiple locations for any individual Standard Connect account, if the merchant operates in multiple physical sites.

curl https://api.stripe.com/v1/terminal/locations \
  -u 
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -d "display_name"="HQ" \
  -d "address[line1]"="1272 Valencia Street" \
  -d "address[city]"="San Francisco" \
  -d "address[state]"="CA" \
  -d "address[country]"="US" \
  -d "address[postal_code]"="94110" \
  -H "Stripe-Account: 
{{CONNECTED_ACCOUNT_ID}}
"

Create a location with Custom Connect

For Custom Connect integrations, locations belong to the platform account and are not mapped strictly to Connect accounts. If your platform needs to associate Custom Connect accounts with locations, you can store a reference to the relevant account(s) in the location’s metadata property.

curl https://api.stripe.com/v1/terminal/locations \
  -u 
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -d "display_name"="HQ" \
  -d "address[line1]"="1272 Valencia Street" \
  -d "address[city]"="San Francisco" \
  -d "address[state]"="CA" \
  -d "address[country]"="US" \
  -d "address[postal_code]"="94110" \
  -d "metadata[connected_account]"=
{{CONNECTED_ACCOUNT_ID}}

You can also create locations from the Stripe Dashboard, under Locations.

When you register your reader to a location, the specified location groups the reader and defines its country settings.

Scope connection tokens Server-side Smart readers

When creating a ConnectionToken for the Terminal SDK, you may provide a location parameter to control access to smart readers. If you provide a location, the ConnectionToken is only usable with smart readers assigned to that location. If you don’t provide a location, the ConnectionToken is usable with all readers.

curl https://api.stripe.com/v1/terminal/connection_tokens \
  -u 
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -d "location"=
{{LOCATION_ID}}

Register a reader to a location

You must register your reader to a location in order to accept payments. The process for registering your reader to a location differs based on whether it’s an smart reader or a Bluetooth reader.

Smart readers Server-side

Register smart readers (Verifone P400 and BBPOS WisePOS E) to a location during reader registration.

curl https://api.stripe.com/v1/terminal/readers \
  -u 
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -d "registration_code"="{{READER_REGISTRATION_CODE}}" \
  -d "label"="Alice's Reader" \
  -d "location"=
{{LOCATION_ID}}

You can also register readers in the Dashboard, under Locations.

Bluetooth readers Client-side

Register Bluetooth readers (Stripe Reader M2, BBPOS Chipper 2X BT, and BBPOS WisePad 3) to a location while connecting to the reader by specifying the locationId in your BluetoothConnectionConfiguration. If you’d like, you can register the reader to the last used location by passing in the reader.locationId from a discovered reader.

Filter discovered readers

Smart readers Client-side

Your application uses the SDK’s discoverReaders method to look for readers it can connect to. When discovering a smart reader like the Verifone P400 or BBPOS WisePOS E, you can discover the intended reader more easily by filtering results by location.

With the code below, only readers in a given location are returned to your app’s callback. You can find the location’s ID in the Dashboard, under Locations.

async function discoverReaders() {
  const config = {simulated: false, location: 
'{{LOCATION_ID}}'}
  const discoverResult = await terminal.discoverReaders(config);
  if (discoverResult.error) {
    console.log('Failed to discover: ', discoverResult.error);
  } else if (discoverResult.discoveredReaders.length === 0) {
    console.log('No available readers.');
  } else {
    // You should show the list of discoveredReaders to the
    // cashier here and let them select which to connect to (see below).
    connectReader(discoverResult);
  }
}

Bluetooth readers Client Side

Because mobile readers use Bluetooth for connection, discoverReaders returns all nearby readers. No additional filtering is applied by default. However, you can use the returned registeredLocation parameter on the Reader object to optionally apply additional filtering in your application.