Orders

Authenticated API

Order endpoints require a valid JWT Bearer token. Accessible via the API gateway at /v1/commerce/orders/*.

Create Order

POST /v1/commerce/orders

Request

Field	Type	Required	Description
source	string	Yes	Order source: "pos", "qr_code", "mobile_app", "kiosk", "online"
currency	string	Yes	ISO 4217 currency code (e.g., "USD")
items	array	Yes	Order line items (see below)
location_id	string (UUID)	No	Location UUID
customer_id	string (UUID)	No	Customer UUID
table_id	string (UUID)	No	Table UUID (for dine-in)
guest_name	string	No	Guest name (for takeout/delivery)
notes	string	No	Order-level notes
send_to_kds	boolean	No	Auto-route to kitchen display (default: false)
metadata	object	No	Custom key-value metadata

Item Fields

Field	Type	Required	Description
name	string	Yes	Item name
quantity	integer	Yes	Quantity
unit_price	number	Yes	Price per unit
menu_item_id	string (UUID)	No	Link to menu item
modifiers	object	No	Modifier selections
notes	string	No	Item-level notes (e.g., "no onions")
course_type	string	No	"fire_now", "appetizer", "main", "dessert"
seat_number	integer	No	Seat number for split checks

Response

{
  "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "tenant_id": "550e8400-e29b-41d4-a716-446655449100",
  "location_id": "550e8400-e29b-41d4-a716-446655449110",
  "source": "pos",
  "status": "pending",
  "currency": "USD",
  "subtotal": 14.99,
  "tax_total": 1.20,
  "discount_total": 0.00,
  "total": 16.19,
  "items": [
    {
      "id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
      "order_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "name": "Margherita Pizza",
      "quantity": 1,
      "unit_price": 14.99,
      "total_price": 14.99,
      "modifiers": {},
      "notes": null
    }
  ],
  "created_at": "2026-02-19T15:30:00Z",
  "updated_at": "2026-02-19T15:30:00Z"
}

Examples

curl

curl -X POST https://dev.api.olympuscloud.ai/v1/commerce/orders \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "source": "pos",
    "currency": "USD",
    "table_id": "550e8400-e29b-41d4-a716-446655440001",
    "send_to_kds": true,
    "items": [
      {
        "name": "Margherita Pizza",
        "quantity": 1,
        "unit_price": 14.99,
        "course_type": "main"
      },
      {
        "name": "Caesar Salad",
        "quantity": 1,
        "unit_price": 9.99,
        "course_type": "appetizer"
      }
    ]
  }'

Python

import requests

TOKEN = "your_jwt_token"

response = requests.post(
    "https://dev.api.olympuscloud.ai/v1/commerce/orders",
    headers={"Authorization": f"Bearer {TOKEN}"},
    json={
        "source": "pos",
        "currency": "USD",
        "send_to_kds": True,
        "items": [
            {"name": "Margherita Pizza", "quantity": 1, "unit_price": 14.99},
            {"name": "Caesar Salad", "quantity": 1, "unit_price": 9.99},
        ],
    },
)
order = response.json()
print(f"Order {order['id']} created. Total: ${order['total']}")

JavaScript

const response = await fetch("https://dev.api.olympuscloud.ai/v1/commerce/orders", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: `Bearer ${token}`,
  },
  body: JSON.stringify({
    source: "pos",
    currency: "USD",
    send_to_kds: true,
    items: [
      { name: "Margherita Pizza", quantity: 1, unit_price: 14.99 },
      { name: "Caesar Salad", quantity: 1, unit_price: 9.99 },
    ],
  }),
});
const order = await response.json();
console.log(`Order ${order.id} created. Total: $${order.total}`);

---

Get Order

GET /v1/commerce/orders/:id

curl https://dev.api.olympuscloud.ai/v1/commerce/orders/b2c3d4e5-f6a7-8901-bcde-f12345678901 \
  -H "Authorization: Bearer $TOKEN"

---

List Orders

GET /v1/commerce/orders

Query parameters:

Parameter	Type	Description
status	string	Filter by status: pending, confirmed, preparing, ready, completed, cancelled
location_id	UUID	Filter by location
limit	integer	Max results (default: 50)
offset	integer	Pagination offset

curl "https://dev.api.olympuscloud.ai/v1/commerce/orders?status=pending&limit=10" \
  -H "Authorization: Bearer $TOKEN"

---

Update Order Status

PUT /v1/commerce/orders/:id/status

curl -X PUT https://dev.api.olympuscloud.ai/v1/commerce/orders/ORDER_ID/status \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"status": "confirmed"}'

Order Status Flow

draft → pending → confirmed → preparing → ready → completed
                                                 ↘ cancelled
                                                 ↘ refunded

---

Calculate Order Total

POST /v1/commerce/orders/calculate

Pre-calculate totals (subtotal, tax, discounts) before submitting an order.

Response

{
  "subtotal": 24.98,
  "tax": 2.00,
  "total": 26.98,
  "tip": 0.00,
  "delivery_fee": 0.00,
  "discount": 0.00
}