Skip to main content
Networks fail mid-request. The question that matters is: if you retry, will something happen twice? With Maple, the writes you’ll retry most are built to be safe to repeat — so you can retry on a timeout without reconciling first.
There is no Idempotency-Key header on this API. You don’t generate or send idempotency keys. Safety is a property of each operation, described below — not something you opt into per request.

​
Order decisions are replay-safe

Repeating an order decision — accept, deny, ready, complete, cancel, or status — returns the same acknowledgement without applying the side effect twice: 
{ "object": "order_decision", "order_id": "ord_...", "decision": "accept", "status": "received" }
If you send accept and the response times out, send it again. The order is accepted exactly once, and you get { "status": "received" } either way. This makes a simple retry-on-transient-error loop correct without any bookkeeping on your side.

​
Publishing a menu is a diff

A menu publish describes the desired state of the whole menu and is applied as a diff against what’s currently published, keyed by your externalIds:
  • Re-publishing an identical document is a no-op.
  • Object identities stay stable across publishes by externalId, so republishing doesn’t recreate or churn objects.
  • Validation is all-or-nothing — a 400 changes nothing, so a failed publish leaves the menu exactly as it was.
So if a publish times out, re-sending the same document is safe. See Publish a menu.

​
Replaying an event is idempotent

POST /v1/webhook_events/{eventId}/replay re-delivers an event only to subscriptions that haven’t already received it. Subscriptions that already got it are skipped, so replaying after an outage won’t double-deliver to healthy endpoints.

​
Your side: dedupe deliveries

The one place you must add idempotency is your webhook handler. Delivery is at-least-once, so the same event can arrive more than once. Dedupe on the envelope id: 
async function handleEvent(event: { id: string; type: string; data: unknown }) {
  if (await alreadyProcessed(event.id)) return; // no-op on a repeat
  await process(event);
  await markProcessed(event.id);
}
Make the work itself idempotent where you can — for example, key your own order records by Maple’s order_id so a duplicate order.notification updates rather than duplicates. Don’t rely on event ordering; reconcile against GET /v1/orders/{orderId} when sequence matters. See Webhooks.

​
Summary

OperationSafe to retry?Why
Order decisionsYesReplay-safe; repeats return received with no double effect
Menu publishYesDiff-applied; identical re-publish is a no-op
Event replayYesSkips subscriptions already delivered to
Receiving webhooksYou dedupeAt-least-once delivery — dedupe on event id