Manage locations

Group and manage your readers by physical location.

You can streamline the management of multiple readers across different physical sites by using locations and zones.

Locations and zones help by associating each reader with specific operational sites and guarantee that the correct regional configurations are downloaded.

Locations: Allows you to group readers, monitor their connectivity status, and modify your settings based on physical location. This functionality is beneficial for marketplaces with multiple connected accounts.
Zones: Offers an optional method to further categorize locations and readers. Zones enable you to represent broader groups of readers or locations, such as larger geographic regions (for example, countries) or organizational sub-brands. Multiple locations can belong to a single zone, and you can create a hierarchical structure by grouping multiple zones under a single zone.

Note

Zones provide an additional way to group locations. You must still assign readers to a location, and you can assign a location to only one zone.

Locations

You can create a location for each physical place where your readers operate. You can register multiple readers to each location, and nest these locations within zones. Before you can use a reader, you must register it to a location.

The required address properties for a location vary by country:

Countries	Required Address Properties
Australia Canada Italy Spain United States	`line1`, `city`, `state`, `postal_code`, and `country`
Austria⁺ Belgium Czech Republic⁺ Denmark Finland⁺ France Germany Luxembourg⁺ Malaysia⁺ 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.

Common mistake

You can use the Dashboard or API to update a Location object. After you create a location, you can’t change its country. Instead, create a new location in the new country, and then re-register any readers associated with the old location.

Zones

Zones are the top-level groups that can consist of either more zones or locations. You can add more zones nested under an existing one, creating additional hierarchy levels, such as “West coast.” However, organizing your locations into zones is optional.

Create locations and zones

Note

You can’t create or modify zones using the API.

First, you must register your reader to a location to accept payments.

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

Create a location for accounts using direct charges

To create a Location for an account using direct charges, use the Stripe-Account header in your request. Only the Connect account you authenticate as can access these locations. If the business operates in multiple physical sites, you can create multiple Locations for any individual accounts with direct charges.

Create a location for accounts using destination charges

For integrations using destination charges, Locations belong to the platform account and aren’t mapped strictly to connected accounts. If your platform needs to associate accounts using destination charges with Locations, you can store a reference to the relevant account(s) in the Location’s metadata property.

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 can 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.

Note

For Bluetooth readers, the location of a ConnectionToken has no effect. This ensures that any nearby Bluetooth readers remain discoverable.