API Ordering Flow

Agent Warning: Launch payment strategy: Stripe-only. Do not prioritize Coinbase x402, USDC, Base, wallet setup, or crypto checkout for launch unless the founder explicitly reopens that decision. x402 remains a long-term architectural direction, not a launch blocker.

This page documents the canonical order flow:

1. GET /v1/menu
2. POST /v1/orders/quote
3. POST /v1/orders/confirm
4. GET /v1/orders/{id}

Core contract references:

• AGENTS guide
• OpenAPI spec
• Generated API reference
• Worked example
• Official MCP repo

Base URL

Development:

export BASE_URL="http://localhost:3000"

1) Fetch menu

curl -sS "$BASE_URL/v1/menu"

2) Create quote

curl -sS -X POST "$BASE_URL/v1/orders/quote" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      { "sku": "PZ-MAR", "qty": 1 },
      { "sku": "DR-COL", "qty": 1 }
    ],
    "fulfillment": { "type": "pickup" },
    "contact": {
      "name": "API Flow Test",
      "phone": "+33600000000",
      "email": "api-flow@example.com"
    }
  }'

Save values from quote response:

• quoteId
• quoteHash
• totalCents
• currency
• expiresAt
• merchantId
• merchantAddress

3) Confirm flow (Stripe card branch)

curl -sS -X POST "$BASE_URL/v1/orders/confirm" \
  -H "Content-Type: application/json" \
  -d '{
    "quoteId": "YOUR_QUOTE_ID",
    "paymentMethod": "card",
    "assertions": {
      "expectedQuoteHash": "sha256:YOUR_QUOTE_HASH",
      "expectedTotalCents": 1200,
      "maxTotalCents": 1200,
      "expectedCurrency": "EUR",
      "expectedPaymentMethod": "card",
      "expectedExpiresAt": "2026-03-03T18:30:00Z",
      "expectedMerchantId": "au-comptoir-a-patons",
      "expectedMerchantAddress": "111 Rue Sebastien Gryphe, 69007 Lyon, France"
    }
  }'

Expected response: hosted Stripe Checkout details. After Stripe payment succeeds, poll the checkout-session status endpoint or follow the storefront return path until the API exposes the paid orderId.

Recovery branches

When confirm fails, use the error code to choose the smallest safe retry path:

• ASSERTION_FAILED_*: quote state drifted; recreate the quote and reuse the new quoteHash, amount, expiry, and merchant assertions.
• PAYMENT_UNAVAILABLE: keep the storefront inactive until Stripe Connect and required card capabilities are ready.

4) Fetch order status

curl -sS "$BASE_URL/v1/orders/YOUR_ORDER_ID"

Notes

• Quote expiry matters: if expired, create a new quote.
• Always use confirm-time assertions in agentic/automated flows to prevent silent divergence.
• For launch deployments, use Stripe card checkout. Any crypto/x402 flow is future/experimental and should not appear in customer-facing launch docs.
• Prefer the on-domain AGENTS and OpenAPI assets above when linking builders into the contract surface.