> 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

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

### Hierarchy recap

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

### Endpoints at a glance

<table><thead><tr><th width="203">Action</th><th>Method and path</th></tr></thead><tbody><tr><td>Create location</td><td><code>POST /Merchants/{id}/locations</code></td></tr><tr><td>List locations</td><td><code>GET /Merchants/{id}/locations</code></td></tr><tr><td>Get location</td><td><code>GET /Locations/{id}</code></td></tr><tr><td>Update location</td><td><code>PUT /Locations/{id}</code></td></tr><tr><td>Disable location</td><td><code>PUT /Locations/{id}/enabled</code></td></tr><tr><td>Delete location</td><td><code>DELETE /Locations/{id}</code></td></tr></tbody></table>

### Business types

The `locationBusinessType` field controls which payment connections are provisioned for the merchant during onboarding. **Set this value carefully — it cannot be changed after boarding without a full application resubmission.**

| Value      | Description                                            | Payment connections provisioned                                                                                                                                |
| ---------- | ------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `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. |
| `virtual`  | Online or remote business. Requires a `website` value. | Virtual wallet connections only. Physical terminal connections are not built.                                                                                  |
| `both`     | Operates both physically and online                    | Both physical and virtual connections are provisioned. Supports all terminal types and tender configurations.                                                  |

> **Important:** If a merchant is boarded with `locationBusinessType: "physical"` and later needs to accept virtual wallet payments, the application must be resubmitted with `"virtual"` or `"both"`. There is no post-boarding maintenance path to add connection types.

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

**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)


---

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