> For the complete documentation index, see [llms.txt](https://developers.bead.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.bead.xyz/entity-management/location-management.md).

# Location Management

A location represents a single store, branch, or business unit that belongs to a merchant. Every terminal, payment, and report ties back to a location, so creating it correctly keeps settlement and analytics clean.

#### Lifecycle

| Phase     | Typical call                                                             | What happens                                                                                                  |
| --------- | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------- |
| Provision | `POST /Merchants/{id}/locations`                                         | Returns a `locationId` used when creating terminals or pulling reporting data                                 |
| Configure | `PUT /Locations/{id}`                                                    | Replace all editable fields including name, tenderTypes, business type, MCC values, ticket sizes, and address |
| Disable   | `PUT /Locations/{id}/enabled`                                            | Stops new payment activity while preserving location history for reporting and settlement                     |
| Operate   | Use `locationId` across terminal creation, reporting, and reconciliation | Dashboards and settlement reports group transactions by location                                              |
| Retire    | `DELETE /Locations/{id}` once no active terminals remain                 | Permanently removes the location record                                                                       |

#### Hierarchy recap

```
Partner
└─ Merchant
   └─ Location
      └─ Terminal
         └─ Payment
```

#### Endpoints at a glance

| Action           | Method and path                  |
| ---------------- | -------------------------------- |
| Create location  | `POST /Merchants/{id}/locations` |
| List locations   | `GET /Merchants/{id}/locations`  |
| Get location     | `GET /Locations/{id}`            |
| Update location  | `PUT /Locations/{id}`            |
| Disable location | `PUT /Locations/{id}/enabled`    |
| Delete location  | `DELETE /Locations/{id}`         |

#### What boarding creates

{% hint style="warning" %}
When an onboarding application reaches `boarded`, Bead automatically creates a default **Location** and one or more default **Terminal(s)** for the merchant. You do not create these yourself. This section documents what Bead creates so you know what to look for. It does not cover manual location or terminal creation, which is unchanged and described elsewhere on this page.
{% endhint %}

Which records get created is driven entirely by the `locationBusinessType` value you submitted on the application:

| `locationBusinessType` | Default Location created      | Default Terminal(s) created                              |
| ---------------------- | ----------------------------- | -------------------------------------------------------- |
| `physical`             | One Location, type `physical` | One Terminal, `type: physical`                           |
| `virtual`              | One Location, type `virtual`  | One Terminal, `type: virtual`                            |
| `both`                 | One Location, type `both`     | Two Terminals: one `type: virtual`, one `type: physical` |

**Integrator sequence**

1. Wait for the application to reach `boarded` (via [Get Status](https://developers.bead.xyz/onboarding/get-status.md) or the boarding webhook). The default Location and Terminal(s) exist at that point, so you can retrieve them immediately.
2. List the merchant's terminals ([List Terminals](https://developers.bead.xyz/entity-management/terminal-management/list-terminals.md)) to identify the default terminal(s) Bead created.
3. Reset the API key on each default terminal you will use ([Reset Terminal API Key](https://developers.bead.xyz/entity-management/terminal-management/reset-terminal-api-key.md)) and store the `apiKey.secret` from the reset response. List Terminals and Get Terminal return only the masked value, so reset is the only way to obtain the terminal payments API key.
4. Make the credentials available to the reseller.

A terminal Bead creates at boarding has not had its key delivered to anyone, so the first reset does not interrupt an integration. Resetting again later replaces the key immediately, so do it only when you are ready to update every system that uses the current key.

After boarding, you may create additional terminals or edit the defaults as needed. See [Terminal Management](https://developers.bead.xyz/entity-management/terminal-management.md).

**Distinguishing default terminals**

There is no field that marks a terminal as Bead-created versus integrator-created. No `isDefault`, `source`, or similar flag exists on the terminal record. `type` (`virtual` or `physical`) is the only distinguishing attribute available.

For a `both`-type boarding, `type` is sufficient to tell the two default terminals apart from each other and to route each credential to the correct acceptance channel (virtual vs. physical). It is **not** sufficient to tell a default terminal apart from a same-type terminal you create later. If you create a second `physical` terminal on the same location, you must track which one is the original default yourself (for example, by recording the terminal `id` returned at the earliest post-boarding [List Terminals](https://developers.bead.xyz/entity-management/terminal-management/list-terminals.md) call, or by naming or tagging terminals you create so they are distinguishable from Bead's defaults going forward).

#### Business types

The `locationBusinessType` field controls which payment connections are provisioned for the merchant during onboarding, and which default Location and Terminal(s) Bead creates at boarding (see [What boarding creates](#what-boarding-creates) above). **Set this value carefully. What matters is the value at boarding, not the value you first submitted.**

| Value      | Description                                            | Payment connections provisioned                                                                                                                                | Records created at boarding                                                             |
| ---------- | ------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
| `physical` | Brick-and-mortar store or branch                       | Physical connections only. Virtual wallet connections (Klarna, USDC, Lightning, etc.) are not built. Virtual terminals using wallet or BNPL tenders will fail. | One Location (type `physical`) and one Terminal (`type: physical`)                      |
| `virtual`  | Online or remote business. Requires a `website` value. | Virtual wallet connections only. Physical terminal connections are not built.                                                                                  | One Location (type `virtual`) and one Terminal (`type: virtual`)                        |
| `both`     | Operates both physically and online                    | Both physical and virtual connections are provisioned. Supports all terminal types and tender configurations.                                                  | One Location (type `both`) and two Terminals: one `type: virtual`, one `type: physical` |

{% hint style="info" %}
**`locationBusinessType` can still change while the application is in flight.** Before boarding, you can update the value on the application. Bead does not require a full resubmission just to correct it pre-boarding. What matters is the value at the moment the application boards, not the value you first submitted.

**After boarding is a different story.** If a merchant boards with `locationBusinessType: "physical"` (or `"virtual"`) and later needs to accept payments in the other environment (the common case is a merchant boarded `"virtual"` who later wants to take payments in store), adding that environment is account maintenance, not a resubmission. It will likely trigger a new compliance review scoped to the added environment. That review cycle is the real cost of getting this wrong at boarding.
{% endhint %}

**Don't default to `"both"` to sidestep this.** Selecting `"both"` when a merchant only needs one environment is not a safe hedge. It attracts more scrutiny at compliance review than a scoped, correct selection. Set the value to match what the merchant actually needs at boarding.

#### Best practices

**Create under the correct merchant.** Pass the correct `merchantId` so dashboards roll up by store.

**Set the right business type before submission.** The `locationBusinessType` value determines which payment connections are built at boarding time, and which default Location and Terminal(s) are created. If your merchant needs to accept virtual wallet tenders (Klarna, USDC, crypto, etc.), use `"virtual"` or `"both"`. A `"physical"`-only boarding cannot support Virtual terminals.

**Don't recreate what boarding already created.** Check for the default Location and Terminal(s) before provisioning new ones. See [What boarding creates](#what-boarding-creates). Creating a duplicate terminal after boarding leaves two valid terminals on the location and creates ambiguity about which credentials the reseller should use.

**Disable before delete.** Use `PUT /Locations/{id}/enabled` to stop new payments before decommissioning a location.

**Use consistent naming.** A clear pattern such as city and store number helps support teams locate a store quickly.

**Tender type inheritance.** A terminal inherits `tenderTypes` from its parent location unless overridden, and a location inherits merchant defaults if `tenderTypes` is omitted at creation.

#### Related pages

* [Create Location](https://developers.bead.xyz/entity-management/location-management/create-location.md)
* [List Locations](https://developers.bead.xyz/entity-management/location-management/list-locations.md)
* [Get Location](https://developers.bead.xyz/entity-management/location-management/get-location.md)
* [Update Location](https://developers.bead.xyz/entity-management/location-management/update-location.md)
* [Delete Location](https://developers.bead.xyz/entity-management/location-management/delete-location.md)
* [Terminal Management](https://developers.bead.xyz/entity-management/terminal-management.md)
* [List Terminals](https://developers.bead.xyz/entity-management/terminal-management/list-terminals.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://developers.bead.xyz/entity-management/location-management.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
