Sign in
An image of the Stripe logo
Create account
Sign in
Home
Payments
Business operations
Financial services
Developer tools
No-code
All products
Home
Payments
Business operations
Home
Payments
Business operations
Financial services
Developer tools
Overview
Online payments
Products and prices
Invoicing
Subscriptions
Quotes
In-person payments
    Overview
    What is Terminal
    Design an integration
    Example applications
    Quickstart
    Accept an in-person payment
    Set up your reader
    Set up your integration
    Connect to a reader
    Collect payments
    Regional considerations
    Supported card brands
    Terminal payments features
    Multiparty payments with Connect
    Collect tips
    Save cards for future use
    Refund transactions
    Provide receipts
    Cart display
    Incremental authorizations
    Extended authorizations
    Operate offline
    Deploy at scale
    Order hardware
    Manage locations
    Configure readers
    References
    API references
    Bluetooth readers
    Smart readers
    SDK migration guide
    Testing
    Deployment checklist
    Stripe Terminal reader product sheets
Multiparty payments
After the payment
Add payment methods
Payment Links
Stripe Checkout
Stripe Elements
About the APIs
Regulation support
Implementation guides
Testing
Terminal
·
HomePaymentsIn-person payments

Manage locations

Group and manage your readers by physical location.

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.

Command Line
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:

CountriesRequired Address Properties
Australia+
Canada
Italy+
Spain+
United States
line1, city, state, postal_code, and country
Austria+
Belgium+
Czech Republic+
Denmark+
Finland+
France
Germany
Luxembourg+
Netherlands
New Zealand+
Norway+
Portugal+
Sweden+
Switzerland+
United Kingdom
line1, city, postal_code, and country
Ireland
Singapore+
line1, postal_code, and country
+Terminal is currently in beta in this country.
**Compatibility for this mobile SDK also applies when used with React Native.

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.

Command Line
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.

Command Line
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.

For Bluetooth readers, the location of a ConnectionToken has no effect. This ensures that Bluetooth readers near you are always discoverable.

Command Line
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.

Command Line
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.

Terminal SDK versions prior to v2.0.0 don’t support registering BBPOS Chipper 2X BT or WisePad 3 readers to locations.

Filter discovered readers

Smart readers Client-side

SDK Reference

  • discoverReaders (JavaScript)
  • discoverReaders (iOS)
  • discoverReaders (Android)
  • discoverReaders (React Native)

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.

Was this page helpful?
Need help? Contact Support.
Watch our developer tutorials.
Check out our product changelog.
Questions? Contact Sales.
Powered by Markdoc
You can unsubscribe at any time. Read our privacy policy.
On this page
Create a location
Scope connection tokens
Register a reader to a location
Filter discovered readers
Stripe Shell
Test mode
Welcome to the Stripe Shell! Stripe Shell is a browser-based shell with the Stripe CLI pre-installed. Login to your Stripe account and press Control + Backtick on your keyboard to start managing your Stripe resources in test mode. - View supported Stripe commands: - Find webhook events: - Listen for webhook events: - Call Stripe APIs: stripe [api resource] [operation] (e.g. )
The Stripe Shell is best experienced on desktop.
$