Get started
Quickstart
Sign up, create an app and a test key, make your first call, and place a test order.
Place your first test order. Sign-up is open to anyone: go to developers.maple.inc, create an organization and an app. The first four steps below match the checklist on the console’s Home page.
You work in test mode first. A mpk_test_… key reaches only test restaurants, and every call goes to https://api.maple.inc/v1. See Test and live modes.
Start with a coding agent
If a coding agent (Claude Code, Cursor, Codex, or similar) is building your integration, copy this prompt into it once you have a test key in MAPLE_KEY. It points the agent at these docs and the API reference, keeps it in test mode, and tells it how to report anything in the API that gets in its way.
Set up a coding agent to build against the Maple Developer API in test mode.
Show prompt
You are building an integration with the Maple Developer API in this repository.
Read these first:
- The docs index: https://docs.maple.inc/llms.txt
- The quickstart: https://docs.maple.inc/developer-api/quickstart
- The OpenAPI spec, which is the source of truth for every endpoint and field: https://docs.maple.inc/openapi/developer-api.json
Rules:
- Use test mode only. The base URL is
https://api.maple.inc/v1, and the key is in theMAPLE_KEYenvironment variable (it starts withmpk_test_). Never print, log, or commit the key, and ask me before using a live key (mpk_live_). - Send the key as
Authorization: Bearer $MAPLE_KEY. Start by callingGET /meto confirm the app, the environment, and the scopes the key has, and plan around those scopes. - Keep the
x-request-idheader from every response. It identifies the request in the developer console and in feedback. - Branch on an error’s
_tagandcode, never itsmessage. FollowRetry-Afteron a 429. - Verify the HMAC signature on every webhook before acting on it.
When the API gets in your way (a bug, a capability you need that is missing, docs that disagree with what the API does, or an error that does not tell you what to change), report it with POST /v1/feedback, citing the x-request-id values involved, then carry on with the best workaround you have. See https://docs.maple.inc/developer-api/concepts/feedback for the fields.
Start by reading the docs above, calling GET /me, and telling me what the key can do and which guide fits what we are building.
Create an app
Sign in at developers.maple.inc, create an organization, and create an app. The console’s Home page shows your progress: Your first order in 4 steps.
Get a test key
On Home, choose Create test key. Name it and select only the scopes your client needs. Save the full key securely: it is shown once and cannot be retrieved after you close the dialog.
Set it in your own environment. The examples read it from
MAPLE_KEY; do not paste a key into documentation, source control, screenshots, or request-history fields.export MAPLE_BASE="https://api.maple.inc/v1"export MAPLE_KEY="mpk_test_..."A suspended or revoked app cannot authenticate with its keys. You can still inspect and revoke keys in the console.
Make your first call
Run the
curlcommand that Home shows, or:curl --include "$MAPLE_BASE/me" \-H "Authorization: Bearer $MAPLE_KEY"Response {"object": "developer_app","id": "dap_...","name": "Your Integration","environment": "test","scopes": ["locations:read", "orders:read", "orders:write"]}Home listens for the call and ticks the step when it arrives. Confirm the app, environment, and scopes. Keep the
x-request-idresponse header to find this call in Requests. A key’s permissions never exceed the app’s scopes.Place a test order
Create a test restaurant: on Home choose Create test restaurant, or open Restaurants and choose New restaurant. Give it a name and time zone, and leave Add a sample menu on for six items ready to order. The console grants your app access to the restaurant and makes your app its order receiver. You need no grant from anyone else.
Then, on the app’s Restaurants page, choose Place test order. The app must be active and hold
orders:write; addorders:readto see the outcome on the restaurant’s card. The order is a real pay-in-store pickup order that goes through the normal workflow. No card is charged. Maple sends theorder.notificationonly to webhook endpoints that exist when the order is placed, and you register one in the next step. To read this order now, callGET /v1/orderswith a key that holdsorders:read; to see the webhook, place another test order after you register the endpoint. See Test the full order workflow.To read the restaurant through the API, call
GET /locationswith a key that holdslocations:read:curl --include "$MAPLE_BASE/locations" \-H "Authorization: Bearer $MAPLE_KEY"For orders, follow Receive and decide orders.
Register and test a webhook
Open Webhooks → Endpoints, choose Add endpoint, enter a public HTTPS URL you control, and select event types. Endpoints in the console need no scope. A key that subscribes through the API needs the read scope of each event type, such as
orders:readfor order events.Save the one-time signing secret and implement signature verification in your receiver. Creating an endpoint does not send a test.
Choose Send test. A delivered result means the receiver returned a
2xx; it does not prove your handler verified the signature. A failed or skipped test is not a success. A test is one attempt, with no automatic retry.Find the request and delivery
In Requests, search for the
x-request-idfrom your API call. Inspect its status and safe error summary. History covers requests made with your app’s keys or tokens, including revoked ones, and is kept for 7 days; requests without a recognized credential are not recorded. An unavailable history service is not an empty history.In Webhooks → Deliveries, inspect the test’s outcome, attempt count, HTTP status, and timestamps. The history is an aggregate per event and endpoint, not a per-attempt timeline.
For a replayable business event, Review event previews a retry. Confirm it to retry eligible destinations; successful pairs and disabled destinations are skipped. Test-only rows offer Send another test. See Webhooks for limits and uncertain outcomes.
Revoke the key you no longer need
When a temporary key is no longer needed, choose Revoke in the console and confirm. Repeat the
/merequest with that key and check that authentication fails. Do not revoke a key another client still uses.
Going live
When your integration works in test mode, open Go live in the console, finish its checks and submit the app for review. A certified app can create mpk_live_… keys. See Going live.
If you get stuck
| What you see | What to check |
|---|---|
| No test restaurants | Create one on Home or Restaurants; a test key reaches only test restaurants |
| An empty location list | locations:read on the key, and that the key is a test key |
| Place test order is unavailable | The app is active, holds orders:write, and has a test restaurant |
| No recent requests | The request ID, filters, the 7-day retention, and that you called with a key for this app |
| History unavailable | Retry the read later; key and webhook management are separate |
| Disabled endpoint | Its configuration and failure history, before you re-enable it |
| Suspended app | Contact Maple; creating another key does not bypass app status |
404 on a restaurant |
Your app has no grant on it in this key’s mode; a test key does not see live grants |
wrong_environment |
Your app has a grant in this key’s mode on a restaurant of the other kind (test or real) |