Quickstart

By the end of this page you’ll have made your first authenticated call, listed the locations your app can reach, and received a real signed webhook at your own endpoint — all in test mode, against isolated data you can’t break.

Before you begin

You need a sandbox API key (mpk_test_…). The Maple team issues one when they create your developer app during onboarding. If you don’t have one yet, contact us — it takes us a few minutes. That’s the only prerequisite. There’s no SDK to install; every example here is plain curl you can paste into a terminal. You’ll work against the sandbox the whole way — isolated data you can’t break. (Production lives at https://api.maple.inc/v1; see Environments.)

Keep your key and the sandbox base URL in environment variables so you can copy the examples verbatim:

export MAPLE_KEY="mpk_test_..."
export MAPLE_BASE="https://api.staging.maple.inc/v1"

Confirm the API is reachable

/ping needs no credential. A clean response means your network can reach Maple.

curl $MAPLE_BASE/ping

Response

{ "object": "developer_api_status", "status": "ok", "version": "..." }

Make your first authenticated call

GET /v1/me echoes back the app your credential belongs to, the environment it operates in, and the scopes it holds. It’s the fastest way to confirm a key works.

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

Response

{
  "object": "developer_app",
  "id": "dap_...",
  "name": "Your Integration",
  "environment": "test",
  "scopes": ["locations:read", "connections:write", "orders:read", "orders:write", "webhooks:write"]
}

environment reads test. A test key can only ever see test data — nothing you do here touches a live merchant.

If you get a 401, the key is missing, malformed, or inactive. See Errors.

List the locations you can reach

Each restaurant your app integrates is a location a merchant has granted you access to. List the ones you can see:

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

Response

{
  "object": "list",
  "data": [
    { "object": "location", "id": "str_test_123", "name": "Maple Test Kitchen", "status": "active", "timezone": "America/New_York", "...": "..." }
  ]
}

During onboarding we grant your test app at least one test location to build against. Note its id.

Connect to a location

A grant lets you see a location. A connection makes your app its order receiver — orders only route to you after this call.

curl -X POST $MAPLE_BASE/locations/str_test_123/connection \
  -H "Authorization: Bearer $MAPLE_KEY"

Response

{ "object": "connection", "location_id": "str_test_123", "status": "active", "...": "..." }

Connections are exclusive per environment: if another app already holds the location, you get a 409. Read How Maple works for the full grant-versus-connection model.

Receive your first signed webhook

Register an HTTPS endpoint you control. (For local testing, a tunnel such as ngrok or Cloudflare Tunnel gives you a public URL.)

curl -X POST $MAPLE_BASE/webhook_subscriptions \
  -H "Authorization: Bearer $MAPLE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "notification_url": "https://your-app.example.com/maple/webhooks",
    "event_types": ["order.notification"]
  }'

The response includes a one-time signing secret (mwhsec_…). Store it now — it is never shown again.

Response

{
  "object": "webhook_subscription.created",
  "subscription": { "object": "webhook_subscription", "id": "dws_...", "status": "enabled", "...": "..." },
  "signing_secret": "mwhsec_..."
}

Now fire a synthetic delivery to that endpoint to confirm it’s wired up:

curl -X POST $MAPLE_BASE/webhook_subscriptions/dws_.../test \
  -H "Authorization: Bearer $MAPLE_KEY"

Response

{ "object": "webhook_test_result", "event_id": "evt_...", "delivered": true, "response_status": 200 }

delivered: true with a 2xx response_status means Maple reached your endpoint and it accepted the event. You’re receiving webhooks.

You just did the whole loop in miniature

Authenticate, find a location, connect to it, and receive a signed event — that’s the spine of every Maple integration. Everything else is filling it in.

Where to go next

Receive and decide orders

Verify webhook signatures and drive real orders with accept / deny / ready / complete.

Publish a menu

Push a location’s menu so the items in your orders map to your own IDs.

Webhooks in depth

Signature verification, delivery guarantees, retries, and replay.

Authentication

API keys, environments, and scopes.

Get started

Orders

Menus

Core concepts

Tutorials

API reference

Endpoints

Resources

Before you begin

You just did the whole loop in miniature

Where to go next

Receive and decide orders

Publish a menu

Webhooks in depth

Authentication

​Before you begin

​You just did the whole loop in miniature

​Where to go next

Receive and decide orders

Publish a menu

Webhooks in depth

Authentication

Before you begin

You just did the whole loop in miniature

Where to go next