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

```mermaid theme={null}
flowchart TD
  Org[Organization] --> M1[Merchant]
  Org --> M2[Merchant]
  M1 --> L1[Location]
  M1 --> L2[Location]
  M2 --> L3[Location]
```

## The three levels

<ParamField path="Organization" type="top-level account">
  The top-level account — a brand group or company. An organization contains one or more merchants.
</ParamField>

<ParamField path="Merchant" type="a business / brand">
  A business under an organization (for example, a single restaurant brand). A merchant owns billing and payment setup, and contains one or more locations.
</ParamField>

<ParamField path="Location" type="a single restaurant">
  One physical restaurant — the unit the Developer API works with. A location belongs to exactly one merchant. Its ID looks like `str_…`, and the API exposes it as the `location` resource.
</ParamField>

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

<Info>
  **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](/developer-api/how-maple-works) for grants and connections.
</Info>

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

<Steps>
  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Deprovisioned">
    The merchant revokes the grant. You receive **`store.deprovisioned`** and lose access to the location entirely.
  </Step>
</Steps>

A location has at most one connected app per environment, so a `POST` to a location another app already holds returns `409`. See [Webhooks](/developer-api/concepts/webhooks) 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.