Skip to content
Maple

Get started

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 integration, which belongs to a developer organization you create at developers.maple.inc. Organization members create keys in the developer console. Credentials, grants, and subscriptions belong to one mode, test or live. Maple certifies an app before it can use live keys.

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. Reading its orders, catalog and delivery zones needs only the grant and the read scope.

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.

Catalog what they order from

The menu you publish 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 --> Catalog[Catalog]
  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 catalog 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 catalog
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.

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

One host, https://api.maple.inc/v1, serves two modes. Your key sets the mode:

  • Test — a mpk_test_… key reaches test restaurants you create in the console.
  • Live — a mpk_live_… key reaches real restaurants that granted your app access.

You build and verify everything in test mode, then use a live key once Maple certifies your app. The two modes never see each other’s data. More in Test and live modes.

Next