Public API

Orders

Create orders and (with a secret key) read order details.

Create an order

POST/orderspublishable or secret

Request

curl -X POST https://www.kitchensflow.com/api/public/v1/orders \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "productId": "bbq-bacon",
        "quantity": 1,
        "selectedOptions": [
          { "groupId": "taille", "optionId": "double", "quantity": 1 }
        ]
      }
    ],
    "customer": { "name": "Yasmine B.", "phone": "+212600112233" },
    "fulfillment": "pickup",
    "paymentMethod": "pay_at_pickup",
    "locationId": "casa-maarif",
    "idempotencyKey": "3d3917e0-1fd2-46b3-a85d-aef83a9734a4"
  }'

Body fields

Field	Required	Notes
items[].productId	yes	Must exist and be available
items[].quantity	yes	1–50 per line
items[].selectedOptions	no	{ groupId, optionId, quantity? }[] — prices ignored
items[].notes	no	Max 200 chars
customer.name	yes
customer.phone	yes
customer.email	no
fulfillment	no	pickup (default), delivery, table
paymentMethod	yes	pay_at_pickup or cash_on_delivery
locationId	conditional	Required when the restaurant has more than one location; optional (auto) for single-location tenants
idempotencyKey	recommended	UUID v4 — see below

Response

json

{
  "order": {
    "id": "3d3917e0-1fd2-46b3-a85d-aef83a9734a4",
    "totalCentimes": 20300,
    "currency": "MAD",
    "status": "created",
    "paymentStatus": "pending",
    "paymentMethod": "pay_at_pickup",
    "fulfillment": "pickup",
    "locationId": "casa-maarif",
    "createdAt": "2026-07-30T14:46:05.115Z"
  }
}

Idempotency

Generate one UUID v4 per checkout attempt. Retries with the same key return the same order instead of creating a duplicate.

Reuse the key for retries of the same cart. Generate a fresh one when the customer starts a new order.

javascript

const idempotencyKey = crypto.randomUUID();

Retrieve an order

GET/orders/:idsecret only

Returns the full order including customer details. Rejected for publishable keys so PII is never reachable from the browser.

Line merging

Lines with the same productId but different selectedOptions stay separate.

Identical lines (same product, options, and notes) are merged by quantity.