Skip to content
Maple

API reference

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/v1

A 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. 450 means $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’s menu_entity_id carries the externalId you published for that menu object.
  • Timestamps on events and orders are Unix seconds (the created field).
  • Object typing. Most resources carry an object field (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/orders returns 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_events returns up to 50 events, most recent first.
  • GET /v1/locations and GET /v1/webhook_subscriptions return 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.