> 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/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](/onboarding/get-status.md) or the boarding webhook).
2. List the merchant's terminals ([List Terminals](/entity-management/terminal-management/list-terminals.md)) to identify the default terminal(s) Bead created.
3. Read the credentials off those terminals — each terminal's `apiKey.secret` is the terminal payments API key.
4. Make the credentials available to the reseller.

After boarding, you may create additional terminals or edit the defaults as needed — see [Terminal Management](/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](/entity-management/terminal-management/list-terminals.md) call, or by naming/tagging terminals you create so they're 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](/entity-management/location-management/create-location.md)
* [List Locations](/entity-management/location-management/list-locations.md)
* [Get Location](/entity-management/location-management/get-location.md)
* [Update Location](/entity-management/location-management/update-location.md)
* [Delete Location](/entity-management/location-management/delete-location.md)
* [Terminal Management](/entity-management/terminal-management.md)
* [List Terminals](/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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.