Organizations, merchants, and locations

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.

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