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

<ParamField path="Developer app" type="your identity">
  Your integration. Maple creates it during onboarding and issues its credentials. An app operates in **test** or **live**, never both at once — the credential you use selects which.
</ParamField>

<ParamField path="Location" type="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](/developer-api/concepts/entities).
</ParamField>

<ParamField path="Connection" type="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.
</ParamField>

<ParamField path="Order" type="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.
</ParamField>

<ParamField path="Menu" type="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.
</ParamField>

<ParamField path="Webhook subscription" type="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.
</ParamField>

## How they connect

```mermaid theme={null}
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.

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

## 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](/developer-api/guides/receive-orders#optional--pre-validate-orders).
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](/developer-api/guides/receive-orders).

## 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](/developer-api/concepts/environments).

## Next

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/developer-api/quickstart">
    Make the first calls yourself.
  </Card>

  <Card title="Authentication" icon="key" href="/developer-api/concepts/authentication">
    API keys, environments, and scopes in detail.
  </Card>
</CardGroup>