Skip to main content
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.

​
The three levels

​
Organization
top-level account
The top-level account — a brand group or company. An organization contains one or more merchants.
​
Merchant
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.
​
Location
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.

​
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.
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:
StatusMeaning
activeLive and accepting orders
pausedTemporarily not accepting orders
inactiveNot 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

ResourceID prefixIn the Developer API?
Locationstr_…Yes — the location resource and every location_id
Orderord_…Yes
Webhook subscriptiondws_…Yes
Eventevt_…Yes
Merchant and organization IDs exist internally but aren’t part of the Developer API surface — you address everything by location.