Skip to content
Maple

Get started

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.

Open in Cursor
Show prompt

You are building an integration with the Maple Developer API in this repository.

Read these first:

Rules:

  • Use test mode only. The base URL is https://api.maple.inc/v1, and the key is in the MAPLE_KEY environment variable (it starts with mpk_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 calling GET /me to confirm the app, the environment, and the scopes the key has, and plan around those scopes.
  • Keep the x-request-id header from every response. It identifies the request in the developer console and in feedback.
  • Branch on an error’s _tag and code, never its message. Follow Retry-After on 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.

  1. 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.

  2. 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.

  3. Make your first call

    Run the curl command 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-id response header to find this call in Requests. A key’s permissions never exceed the app’s scopes.

  4. 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; add orders:read to 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 the order.notification only to webhook endpoints that exist when the order is placed, and you register one in the next step. To read this order now, call GET /v1/orders with a key that holds orders: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 /locations with a key that holds locations:read:

    curl --include "$MAPLE_BASE/locations" \
    -H "Authorization: Bearer $MAPLE_KEY"

    For orders, follow Receive and decide orders.

  5. 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:read for 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.

  6. Find the request and delivery

    In Requests, search for the x-request-id from 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.

  7. Revoke the key you no longer need

    When a temporary key is no longer needed, choose Revoke in the console and confirm. Repeat the /me request 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)

Continue with your integration