Orders

A product order captures what was bought, what it costs, where it ships, and how it's fulfilled. Each order has one or more items (with the product, variant, and SKU captured at order time), a complete pricing breakdown including shipping and tax, a shipping address and fulfillment details, and a status that advances from received to delivered.

In the TypeScript SDK each order item references a variantId; the Python SDK identifies items by product_id and sku.

Create an order

TypeScript

const order = await client.productOrders.create({
  customerId: 'cust_456',
  orderDate: Date.now(),
  items: [
    {
      productId: 'product_123',
      variantId: 'variant_456',
      itemName: 'Wireless Headphones',
      quantity: 1,
      unitPrice: 199.99,
      totalPrice: 199.99,
    },
  ],
  pricing: {
    subtotal: 199.99,
    total: 199.99,
  },
});

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

Python

from time import time

from wiil.models.business_mgt import CreateProductOrder, OrderAddress, OrderPricing, ProductOrderItemBase

order = client.product_orders.create(
    CreateProductOrder(
        items=[
            ProductOrderItemBase(
                product_id="product_123",
                item_name="Wireless Headphones",
                sku="WH-2024-BLK",
                quantity=1,
                unit_price=199.99,
                total_price=199.99,
            )
        ],
        customer_id="cust_456",
        pricing=OrderPricing(subtotal=199.99, tax=16.00, shipping_amount=9.99, total=225.98, currency="USD"),
        order_date=int(time() * 1000),
        shipping_address=OrderAddress(
            street="123 Main St", city="New York", state="NY", postal_code="10001", country="US"
        ),
        shipping_method="Standard",
        source="web",
    )
)

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

Get and list

TypeScript

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

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

Python

from wiil.types import PaginationRequest

order_details = client.product_orders.get("order_123")
customer_orders = client.product_orders.get_by_customer(
    "cust_789", PaginationRequest(page=1, page_size=20)
)

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

Update, status, cancel, delete

Order updates, status transitions, cancellation, and deletion are exposed through the TypeScript SDK.

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

const updated = await client.productOrders.update({
  id: 'order_123',
  pricing: { subtotal: 180.00, total: 180.00 },
});

const advanced = await client.productOrders.updateStatus('order_123', {
  id: 'order_123',
  status: OrderStatus.CONFIRMED,
});

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

await client.productOrders.delete('order_123');

ProductOrder fields

Field	Type	Required	Description
id	string	auto	Unique identifier
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
billingAddress / shippingAddress	object | null	No	Addresses (see OrderAddress)
shippingMethod / shippingCarrier / trackingNumber	string | null	No	Fulfillment details
requestedDeliveryDate / shippedDate / deliveredDate	number | null	No	Fulfillment timing
locationId / channelId / terminalId / operatorId	string | null	No	Routing & POS context
orderNumber	string | null	No	Human-readable number (e.g. "ORD-12345")
source	string	No	Order source (default direct)
externalRef	object | null	No	External platform reference
cancelReason / notes	string | null	No	Cancellation reason and staff notes

Pricing

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

OrderAddress

street is required; city, state, postalCode, country, and deliveryInstructions are optional.

Order item (ProductOrderItemBase)

Field	Type	Required	Description
productId	string	Yes	Product reference
variantId	string | null	No	Variant reference (set on TypeScript order items)
itemName	string	Yes	Name captured at order time
sku	string | null	No	SKU captured at order time
quantity	integer	Yes	Quantity (positive)
unitPrice	number	Yes	Price per unit at order time
totalPrice	number	Yes	unitPrice × quantity
warrantyInfo	string | null	No	Warranty terms captured at purchase
status	enum	No	Item fulfillment status (default pending)

Status lifecycle

Status	Meaning
pending	Order received, not started
confirmed	Confirmed by the business
preparing	Warehouse is picking/packing
ready	Ready for shipment
out_for_delivery	With the carrier
completed	Delivered
cancelled	Cancelled (with cancelReason)
returned	Returned

Query options

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

tip

Item names, SKUs, and prices are captured at order time so records stay accurate when the catalog changes. Record trackingNumber and shippingCarrier for fulfillment visibility.