Orders

A menu order captures what a customer ordered, what it costs, and how it moves through the kitchen. Each order has a type (dine-in, takeout, or delivery), one or more items (with applied modifiers), a complete pricing breakdown, and a status that advances from received to fulfilled. Item names and prices are captured at order time, so the record stays accurate even if the menu changes afterwards.

In the TypeScript SDK each order item references a variantId; in the Python SDK each item references a menu_item_id.

Create an order

TypeScript

import { MenuOrderType } from 'wiil-core-js';

const order = await client.menuOrders.create({
  customerId: 'cust_456',
  type: MenuOrderType.DINE_IN,
  orderDate: Date.now(),
  items: [
    {
      menuItemId: 'item_123',
      variantId: 'variant_456',
      itemName: 'Cheeseburger',
      quantity: 2,
      unitPrice: 12.99,
      totalPrice: 25.98,
    },
  ],
  pricing: {
    subtotal: 25.98,
    total: 25.98,
  },
});

console.log(`Order Created: ${order.id}`);

Python

from time import time

from wiil.models.business_mgt import CreateMenuOrder, MenuOrderItemBase, OrderPricing

order = client.menu_orders.create(
    CreateMenuOrder(
        type="dine_in",
        items=[
            MenuOrderItemBase(
                menu_item_id="item_123",
                item_name="Cheeseburger",
                quantity=2,
                unit_price=12.99,
                total_price=25.98,
                special_instructions="No onions",
            )
        ],
        customer_id="cust_456",
        pricing=OrderPricing(subtotal=25.98, tax=2.60, tip=5.00, total=33.58, currency="USD"),
        order_date=int(time() * 1000),
        source="web",
    )
)

print("Order Created:", order.id)

Get and list

TypeScript

const order = await client.menuOrders.get('order_123');
console.log(`${order.status} — $${order.pricing.total}`);

const result = await client.menuOrders.list();
result.data.forEach(o => console.log(`- ${o.id}: ${o.status} ($${o.pricing.total})`));

Python

from wiil.types import PaginationRequest

order = client.menu_orders.get("order_123")
customer_orders = client.menu_orders.get_by_customer(
    "cust_456", PaginationRequest(page=1, page_size=20)
)

print(order.status, customer_orders.meta.total_count)

Update status

The status update carries optional ready-time estimates so the kitchen and customer stay in sync.

TypeScript

import { OrderStatus } from 'wiil-core-js';

const updated = await client.menuOrders.updateStatus('order_123', {
  id: 'order_123',
  status: OrderStatus.PREPARING,
  estimatedReadyTime: Math.floor(Date.now() / 1000) + 15 * 60, // Unix seconds
  actualReadyTime: null,
});

console.log(`Status: ${updated.status}`);

Python

updated = client.menu_orders.update_status(order.id, "preparing")
print("Status:", updated.status)

Cancel

TypeScript

const cancelled = await client.menuOrders.cancel('order_123', {
  cancelReason: 'Customer requested cancellation',
});

Python

cancelled = client.menu_orders.cancel(order.id, reason="Customer requested cancellation")

MenuOrder fields

Field	Type	Required	Description
id	string	auto	Unique identifier
type	enum	Yes	dine_in, takeout, or delivery
status	enum	No	Order status (default pending)
items	array	Yes	Order items (min 1)
customerId	string	Yes	Customer reference
pricing	object	Yes	Pricing breakdown (see below)
orderDate	number	Yes	Unix timestamp of placement
paymentStatus	enum	No	pending, paid, partial, failed, refunded
paymentMethod / paymentReference	string | null	No	Payment details
locationId / channelId / terminalId / operatorId	string | null	No	Routing & POS context
orderNumber	string | null	No	Human-readable number (e.g. "#1234")
requestedTime / estimatedReadyTime / actualReadyTime	number | null	No	Timing
tableNumber	string | null	No	For dine-in
deliveryAddress	object | null	No	street, city, postalCode (for delivery)
specialInstructions / allergies / notes	—	No	Order-level notes & safety info
externalRef	object | null	No	External platform reference
cancelReason	string | null	No	Reason if cancelled

Pricing

The pricing object carries the full breakdown: subtotal and total are required; tax, tip, deliveryFee, discount, and currency are optional.

Order item (MenuOrderItemBase)

Field	Type	Required	Description
menuItemId	string	Yes	Menu item reference
variantId	string	Yes (TS)	Variant reference (TypeScript order items)
itemName	string	Yes	Name captured at order time
quantity	integer	Yes	Quantity (positive)
unitPrice	number	Yes	Price per unit at order time
totalPrice	number	Yes	unitPrice × quantity + modifiers
modifiers	array | null	No	Applied modifiers (see Modifiers)
customizations	array | null	No	name, value, additionalCost
specialInstructions	string | null	No	Item-specific request
status	enum	No	Item prep status (default pending)
menuSetId	string | null	No	Set reference if from a menu set

Status lifecycle

Status	Meaning
pending	Order received, not started
confirmed	Confirmed by the restaurant
preparing	Kitchen is preparing
ready	Ready for pickup/delivery
out_for_delivery	With the delivery driver (delivery orders)
completed	Fulfilled
cancelled	Cancelled (with cancelReason)
returned	Returned

The standard path is pending → confirmed → preparing → ready → completed; delivery orders insert out_for_delivery before completed, and an order can move to cancelled from any state.

Pricing preview

Before submitting, the TypeScript SDK can validate and preview an order's pricing, returning calculated items and pricing, plus errors and warnings (for example, when an item's price has changed). This catches mismatches before the order is placed.

Query options

Orders filter by search, locationId, channelId, terminalId, operatorId, type[], status[], paymentStatus[], customerId, tableNumber, externalSource, and dateRange, sorted by orderDate, createdAt, or totalAmount (asc / desc), with page/pageSize pagination.

tip

Capture item names and prices at order time (the SDKs do this), validate totals with the pricing preview, and record allergies clearly — it is critical for safe food preparation.