Guide · AI agents · reliability

Idempotent orders for AI agents

The single most common way agent checkout breaks in production: the agent retries, and a non-idempotent backend creates a second order and a second charge. Here's exactly why it happens and how idempotent order/checkout APIs stop it.

Why agents retry

Agent frameworks retry tool calls on timeouts, 5xx responses, and dropped connections. That's usually the right behavior — except for writes. If the request to complete a checkout succeeds on the server but the response never reaches the agent, the agent assumes failure and calls again. Now you have two orders.

The dangerous window is small but real: charge captured, response lost. Any write an agent can retry needs a defined "do this at most once" contract.

Two idempotency models

ModelHow it worksUse when
Session-scoped completionCompleting the same checkout session again returns the same order.Agent checkout flows.
Idempotency keyA client-chosen key on order creation; the same key returns the same order, a different payload with the same key returns 409 Conflict.Direct order creation.

How OrderCore does it

Checkout: complete_checkout_session is idempotent per session. Retry it as many times as the agent likes — one order.

// completing the same session twice -> the SAME order id
const a = await complete(session_id);   // { order: { id: "ord_9F3K21" } }
const b = await complete(session_id);   // { order: { id: "ord_9F3K21" } }  (same)

Direct orders: POST /v1/orders takes an idempotency key. Same key + same payload returns the same order; same key + different payload returns 409 Conflict instead of silently diverging.

curl -X POST https://api.ordercore.ai/v1/orders \
  -H "X-API-Key: $ORDERCORE_API_KEY" -H "Idempotency-Key: order-abc-123" \
  -H "Content-Type: application/json" -d '{ ... }'
# same key + different body -> 409 conflict (never a divergent duplicate)

Prove it yourself (no signup)

The demo completes the same session twice and asserts the order IDs match — the exact retry scenario, offline in mock mode:

Run the demo → Quickstart (JS + curl)

Related