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

# How Maple works

> The objects and relationships behind every integration — apps, locations, connections, and the division of responsibility between you and Maple.

Before you write code, it helps to hold the whole model in your head. There are only a handful of objects, and they fit together in one direction.

## The objects

### `Developer app`

your identity

Your approved integration, explicitly assigned to a developer organization by Maple. Invited organization members create keys through the developer console. Credentials, grants, and subscriptions are environment-scoped; sandbox and production are separate deployments. App approval and scope ceilings remain Maple-managed.

### `Location`

a restaurant

A single restaurant — the unit the Developer API works with (ID `str_…`). A merchant **grants** your app access to a location; that grant lets you read it. Locations have a `status` (`active`, `inactive`, `paused`) you should respect. Locations sit under merchants and organizations — see [Organizations, merchants, and locations](https://docs.maple.inc/developer-api/concepts/entities.md).

### `Connection`

you are the order receiver

Connecting to a granted location makes your app its **order receiver**. Orders route to you only after a connection exists. A location can be connected to exactly one app per environment.

### `Order`

what a customer placed

A customer’s order at a connected location, with line items, totals (computed by Maple), and a payment object. You drive it through its lifecycle with decision calls.

### `Menu`

what they order from

The catalog for a location — categories, items, variations, modifiers, and tax and fee definitions — published as one JSON document keyed by your own external IDs.

### `Webhook subscription`

how you hear about events

An HTTPS endpoint plus the event types you want. Maple signs and delivers events to it, and keeps a ledger you can replay from.

## How they connect

```
flowchart LR
  App[Your developer app] -- granted --> Loc[Location]
  App -- connection --> Loc
  Loc -- emits --> Order[Order]
  App -- publishes --> Menu[Menu]
  Order -- order.notification --> Hook[Your webhook endpoint]
  Hook -- accept / deny / ready / complete --> Order
```

A merchant grants you a location → you connect to it → orders from that location are pushed to your webhook → you decide each order. In parallel, you publish the menu those orders are built from.

## Who owns what

This is the most important thing to understand, and the part most restaurant integrations get wrong. Maple owns the parts that carry risk:

| Maple owns                                                   | You own                                               |
| ------------------------------------------------------------ | ----------------------------------------------------- |
| The customer payment lifecycle (Stripe-backed payment links) | Receiving orders and deciding them                    |
| Every customer-facing total, tax, and fee calculation        | Reflecting order state back (accept, ready, complete) |
| Card data and PCI scope                                      | Publishing an accurate menu                           |
| Delivering, retrying, and signing webhooks                   | Verifying signatures and deduping events              |

You never compute a price, touch a card, or build a payment flow. Maple hands you an order with `totals` already final and a `payment` object you can read but don’t manage.

> [!NOTE]
>
> Treat Maple’s totals as authoritative. Your job at order time is to decide whether you can fulfill the order — not to re-price it.

## The order loop, end to end

1. A customer orders at a connected location.
2. *(Optional)* Maple sends `order.validation_requested` and waits for you to confirm the order is fulfillable. See [validating orders](https://docs.maple.inc/developer-api/guides/receive-orders.md).
3. Maple sends `order.notification` with the full order.
4. You **accept** or **deny** it.
5. You report progress — **ready**, then **complete** — or **cancel** if you must after accepting.
6. You receive `order.cancelled` if the customer or store cancels.

Every decision call is replay-safe, so retries are harmless. The full sequence lives in [Receive and decide orders](https://docs.maple.inc/developer-api/guides/receive-orders.md).

## Environments

Maple runs two isolated environments, each with its own base URL:

- **Sandbox** — `https://api.staging.maple.inc/v1`, with your `mpk_test_…` key. For development and testing.
- **Production** — `https://api.maple.inc/v1`, with your `mpk_live_…` key. Live traffic.

You build and verify everything in the sandbox against isolated data, then point the same code at production once your integration is approved. The two never see each other’s data. More in [Environments and test mode](https://docs.maple.inc/developer-api/concepts/environments.md).

## Next

- [Quickstart](https://docs.maple.inc/developer-api/quickstart.md): Make the first calls yourself.
- [Authentication](https://docs.maple.inc/developer-api/concepts/authentication.md): API keys, environments, and scopes in detail.