> ## Documentation Index
> Fetch the complete documentation index at: https://docs.maple.inc/llms.txt
> Use this file to discover all available pages before exploring further.

# Organizations, merchants, and locations

> How Maple structures the businesses you integrate with — and why the Developer API works at the location level.

Maple organizes every business into a three-level hierarchy. You’ll mostly work with the bottom level — locations — but understanding the whole shape prevents wrong assumptions about what an ID refers to and what access you have.

```
flowchart TD
  Org[Organization] --> M1[Merchant]
  Org --> M2[Merchant]
  M1 --> L1[Location]
  M1 --> L2[Location]
  M2 --> L3[Location]
```

## The three levels

### `Organization`

top-level account

The partner account. An organization contains one or more merchants, and its team members can manage all of them.

### `Merchant`

a business / brand

A restaurant business or brand under an organization. A merchant contains one or more locations. Its legal entity holds payment and billing setup.

### `Location`

a single restaurant

One physical restaurant — the unit the Developer API works with, and the unit Maple prices and bills. A location belongs to exactly one merchant. Its ID looks like `str_…`, and the API exposes it as the `location` resource.

## Cardinality, and why it matters

- An organization has **many** merchants; a merchant has **many** locations.
- A location belongs to **exactly one** merchant, and a merchant to **at most one** organization. These don’t move — a location can’t be reparented to another merchant.
- **Operational data lives at the location.** Orders, menus, connections, and webhooks are all scoped to a location, not to a merchant or organization. Two locations under the same merchant are independent as far as your integration is concerned.

## What the Developer API exposes

The Developer API surfaces **locations**. The `location` resource carries the location’s ID (`str_…`), name, status, timezone, phone, and address — not its parent merchant or organization. When you list locations, connect, receive orders, or publish a menu, you’re always operating on a single location by its `str_…` ID.

> [!NOTE]
>
> **Access is per-location.** A merchant grants your app access to specific locations, one at a time. Holding a grant to one location gives you no access to its siblings under the same merchant — each location is granted (and connected) on its own. See [How Maple works](https://docs.maple.inc/developer-api/how-maple-works.md) for grants and connections.

## Location status

A location’s `status` tells you whether it’s open for orders:

| Status     | Meaning                                        |
| ---------- | ---------------------------------------------- |
| `active`   | Live and accepting orders                      |
| `paused`   | Temporarily not accepting orders               |
| `inactive` | Not yet live (setup incomplete) or deactivated |

Respect it — don’t expect orders from, or route work to, a location that isn’t `active`.

## The connection lifecycle

Your access to a location moves through four moments, and three webhook events mark them:

1. ### Provisioned

   A merchant grants your app access to a location. You receive **`store.provisioned`**, and the location appears in `GET /v1/locations`. You can read it — but orders don’t route to you yet.

2. ### Connected

   You call `POST /v1/locations/{id}/connection` to become the location’s order receiver. The connection’s `status` becomes `active`, and **`store.status.changed`** fires with `status: "connected"`. Orders now route to you.

3. ### Disconnected

   You (or Maple) remove the connection with `DELETE`. **`store.status.changed`** fires with `status: "disconnected"` and orders stop routing to you. The grant remains, so you can reconnect later.

4. ### Deprovisioned

   The merchant revokes the grant. You receive **`store.deprovisioned`** and lose access to the location entirely.

A location has at most one connected app per environment, so a `POST` to a location another app already holds returns `409`. See [Webhooks](https://docs.maple.inc/developer-api/concepts/webhooks.md) to subscribe to these events.

## Identifiers you’ll see

| Resource             | ID prefix | In the Developer API?                                 |
| -------------------- | --------- | ----------------------------------------------------- |
| Location             | `str_…`   | Yes — the `location` resource and every `location_id` |
| Order                | `ord_…`   | Yes                                                   |
| Webhook subscription | `dws_…`   | Yes                                                   |
| Event                | `evt_…`   | Yes                                                   |

Merchant and organization IDs exist internally but aren’t part of the Developer API surface — you address everything by location.

For how partners manage organizations, merchants, and locations in the dashboard, see [How Maple is organized](https://docs.maple.inc/partners/overview.md).