API reference
Conventions
Base URL, resource conventions, IDs, money, and list behavior shared across every Developer API endpoint.
The Developer API is a JSON REST API. Every endpoint in this reference is grouped in the sidebar by resource — general (ping and /me), locations, connections, catalog, delivery zones, webhooks, orders, and feedback. This page covers the conventions they all share; the linked concept pages go deeper.
Base URL
One host serves both test and live keys, under the /v1 prefix:
https://api.maple.inc/v1A mpk_test_… key reaches test restaurants and a mpk_live_… key reaches real ones. See Test and live modes.
Authentication
Send a Bearer credential on every request:
Authorization: Bearer mpk_test_…Send your API key (mpk_test_… for test mode, mpk_live_… for live mode) as the bearer token. GET /v1/me returns the app, environment, and scopes for any key. Full detail in Authentication.
Resource conventions
- Opaque IDs carry a type prefix —
str_(location),ord_(order),dws_(webhook subscription),evt_(event), and so on. Treat them as opaque strings. - Money is integer USD cents.
450means $4.50. Never parse amounts as floats. Currency codes are always uppercase ISO‑4217 (USD). - Field casing. Catalog payloads use camelCase (
externalId,minSelections,modifierGroups); order and webhook payloads use snake_case (fulfillment_type,menu_entity_id,payment_status). A line item’smenu_entity_idcarries theexternalIdyou published for that menu object. - Timestamps on events and orders are Unix seconds (the
createdfield). - Object typing. Most resources carry an
objectfield (order,location,event, …) so you can tell them apart.
Lists
List endpoints return an envelope with an object of list and a data array:
{ "object": "list", "data": [ /* … */ ] }Lists return a bounded window with a has_more flag rather than a total count:
GET /v1/ordersreturns up to 100 orders across the locations you hold a grant for. Newest first by default; see the catch-up parameters below.GET /v1/webhook_eventsreturns up to 50 events, most recent first.GET /v1/locationsandGET /v1/webhook_subscriptionsreturn the full set for your app.
Draining orders after downtime
GET /v1/orders takes three optional query parameters, built for reconciling a backlog:
| Parameter | Meaning |
|---|---|
since |
Exclusive ISO 8601 (UTC) checkpoint. With since, results are oldest first so you can drain forward without skipping orders that share a timestamp. |
starting_after |
The last order id (ord_…) from the previous page. Requires since, and the order must belong to your app. |
limit |
Page size, 1–100. Defaults to 100. |
Request GET /v1/orders?since=<checkpoint>&limit=100, then repeat with starting_after set to the last returned order id while has_more is true. There is no location_id filter — filter client-side on location_id.
To make Maple redeliver a webhook rather than pull the order yourself, use POST /v1/orders/{orderId}/resend for a live order, or the event ledger and replay when the original event identity matters.
Errors
Errors use standard HTTP status codes with a JSON body carrying a stable _tag and a human-readable message. Branch on the tag, not the message. The full catalog is in Errors.
Rate limits
Every request you make with an API key or access token counts against budgets for your app in its environment:
| Budget | Live | Test |
|---|---|---|
Per restaurant: requests to one location’s routes (/locations/{locationId}/...) |
120 a minute | 60 a minute |
| Per app: every request, across all your locations | 6,000 a minute | 300 a minute |
A request to a route with {locationId} in its path counts against that location’s budget and your app’s. Every other request (orders by id, lists, webhooks, /me, feedback) counts against your app’s budget only. So an app with 300 restaurants in live can send each of them 120 requests a minute, as long as the total stays under 6,000.
Test has lower budgets on purpose: it is for building and trying things out, not for load. Test and live never share a budget, nor do two apps. Each budget runs in fixed one-minute windows.
Over a budget, the API answers 429 with a DeveloperApiRateLimited body whose message names the budget. Its retry_after field and the Retry-After header both give the seconds until that window resets; wait that long before you retry. A few actions have their own, smaller limits as well: OAuth token requests, and feedback.
If your live integration needs more, contact Maple: we can raise one app’s live budgets, with no change on your side.
Respond to webhooks asynchronously, avoid tight polling loops, and keep the original idempotency key when you retry a write.