API Ordering Flow

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.md
• openapi.yaml
• ADR-0003 repository topology decision
• WORKFLOW.md

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" }
  }'

Save values from quote response:

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

3A) Confirm flow (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: paymentIntentId, clientSecret, and amount details.

3B) Confirm flow (crypto branch)

First call (expect 402 with payment requirements):

curl -i -sS -X POST "$BASE_URL/v1/orders/confirm" \
  -H "Content-Type: application/json" \
  -d '{
    "quoteId": "YOUR_QUOTE_ID",
    "paymentMethod": "crypto"
  }'

From the 402 body, capture paymentRequestId.

Second call (dev mock adapter: use paymentRequestId as PAYMENT-SIGNATURE):

curl -sS -X POST "$BASE_URL/v1/orders/confirm" \
  -H "Content-Type: application/json" \
  -H "PAYMENT-SIGNATURE: YOUR_PAYMENT_REQUEST_ID" \
  -d '{
    "quoteId": "YOUR_QUOTE_ID",
    "paymentMethod": "crypto"
  }'

Expected response: orderId with paid status.

4) Fetch order status

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

Notes

• Quote expiry matters: if expired, create a new quote.
• For crypto, wallet setup is available at GET /v1/wallet-setup.
• Always use confirm-time assertions in agentic/automated flows to prevent silent divergence.