Maple Ordering Integration Guide

​

The short version

​

Step 0 — Onboarding (we do this with you)

• Test credentials for the sandbox environment (https://sandbox.dev-api.maple.inc/v1). Live credentials (https://dev-api.maple.inc/v1) are enabled once your integration is approved. The two environments are fully isolated — test credentials can never touch live merchant data.
• Auth: an API key for early development, with OAuth client-credentials available for long-term server-to-server access. Access is scoped (menus:write, orders:read, orders:write, …) so your app holds only what it needs.
• A webhook URL you register, plus a signing secret for verifying our deliveries. A built-in test endpoint sends you a signed sample event so you can verify your handler before any real traffic.

​

Step 1 — Publish your menu (one endpoint, one document)

POST /locations/{locationId}/menu

{
  "currency": "USD",
  "categories": [
    {
      "externalId": "cat-drinks",
      "name": "Drinks",
      "items": [
        {
          "externalId": "itm-latte",
          "name": "Latte",
          "variations": [
            { "externalId": "var-sm", "name": "Small",
              "price": { "amount": { "amountMinor": 450, "currency": "USD" } } },
            { "externalId": "var-lg", "name": "Large",
              "price": { "amount": { "amountMinor": 550, "currency": "USD" } } }
          ],
          "modifierGroups": [
            { "externalId": "mg-milk", "name": "Milk",
              "minSelections": 1, "maxSelections": 1,
              "options": [
                { "externalId": "mo-whole", "name": "Whole" },
                { "externalId": "mo-oat", "name": "Oat",
                  "price": { "amount": { "amountMinor": 75, "currency": "USD" } } }
              ] }
          ]
        }
      ]
    }
  ]
}

• One write, no sync protocol. You always send the complete document; the server diffs it against the current catalog. There is no object-by-object CRUD, no dependency ordering, no orphan cleanup on your side. Your nightly “export menu → publish” job is the whole sync.
• Your IDs are the keys, and they’re stable. Every object carries your externalId, and the server matches on it across publishes — renames, reprices, and reorders never change an object’s identity. All cross-references inside the document use your IDs, so you map straight from your existing data model with no translation tables.
• Republishing is safe. Publishing an identical document is a no-op. Stock status (an 86’d item, say) survives republishes untouched unless you explicitly set it. You never have to coordinate menu pushes with operational state.
• Validation is all-or-nothing and tells you everything at once. A bad document writes nothing and returns every issue in one response, pointing at the objects in question — so you fix the whole batch in one pass, without back-and-forth with our team.
• Shared modifier groups. Define a group like “Toppings” once and reference it from many items, with per-item overrides (two free toppings on the pizza, max two on the slice). Your menu document stays as small as your menu actually is.

​

Step 2 — Receive and decide orders (one webhook handler)

{
  "event_id": "evt_123",
  "event_type": "orders.notification",
  "location_id": "loc_123",
  "resource_id": "ord_123",
  "resource_type": "order",
  "resource_href": "https://dev-api.maple.inc/v1/orders/ord_123",
  "idempotency_key": "order:ord_123:notification"
}

• Signature verification is standard HMAC-SHA256 with your signing secret (X-Maple-Signature + X-Maple-Timestamp headers) — a few lines in any language, and the subscription test endpoint lets you verify it before go-live.
• Delivery is at-least-once; you dedupe by event_id. Every write you make carries an Idempotency-Key, so retries on your side are always safe too.
• One webhook URL covers everything; you can opt into extra lifecycle echo events later if you want a full event ledger from Maple.

​

Step 3 — Keep stock in sync (optional)

// updateStockStatus
[ { "id": "var_abc123", "stockStatus": "out_of_stock" } ]

​

What a basic integration does not require

• No payment integration. Maple creates and owns the payment link; you never touch a card.
• No price engine. Taxes, fees, and discounts are published as data; Maple computes every customer-facing total.
• No incremental sync protocol. Full-document publish with server-side diffing; IDs stay stable.
• No polling. Orders are pushed to your webhook with a link to the canonical resource.
• No SDK dependency. Plain JSON over HTTPS; any language works.
• No guessing in production. You build and test entirely in the sandbox with test credentials, signed test webhooks, and isolated data before live access is enabled.

​

The growth path (same contract, more fields)

• Tax: categories and rates — percentage, flat, statutory brackets, compound tax-on-tax, tax-inclusive (VAT) pricing.
• Fees: delivery, service charges, bag fees, bottle deposits/CRV, auto-gratuity, and more.
• Discounts & promotions: percentage/amount/BOGO benefits, product-set targeting, scheduling windows, stacking policies, coupon codes with redemption limits.
• Rich modifiers: nested to any depth, shared groups with per-item overrides, quantity rules (“first two toppings free”, “double” options), preselected defaults, free-text entries (cake inscriptions).
• Merchandising metadata: SKUs, barcodes, dietary labels, allergens, calorie counts, day-parted availability (breakfast menus, happy hour).
• Multi-currency: per-currency price overrides with correct minor-unit handling.

​

Summary