How Maple works

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.

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.

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.

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.