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

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 ownsYou own
The customer payment lifecycle (Stripe-backed payment links)Receiving orders and deciding them
Every customer-facing total, tax, and fee calculationReflecting order state back (accept, ready, complete)
Card data and PCI scopePublishing an accurate menu
Delivering, retrying, and signing webhooksVerifying 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.
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.
  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.

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

​
Next

Quickstart

Make the first calls yourself.

Authentication

API keys, environments, and scopes in detail.