Skip to content
Maple

Core concepts

How Maple makes retries safe without an idempotency key — replay-safe decisions, diff-applied catalogs, idempotent replay, and dedupe on your side.

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.

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 catalog is a diff

A catalog publish describes the desired state of the whole catalog 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 catalog 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

Operation Safe to retry? Why
Order decisions Yes Replay-safe; repeats return received with no double effect
Catalog publish Yes Diff-applied; identical re-publish is a no-op
Event replay Yes Skips subscriptions already delivered to
Receiving webhooks You dedupe At-least-once delivery — dedupe on event id