Orders

Orders track customer purchases through their lifecycle. Carts are orders in created state — there is no separate cart entity.

Order States


created → payment_pending → paid → shipped → delivered
                              ↘ cancelled

State	Description
`created`	Active cart
`payment_pending`	Checkout initiated
`paid`	Payment received
`shipped`	Shipped to customer
`delivered`	Received by customer
`cancelled`	Order cancelled

Cart to Order

Carts are orders in created state. During checkout, shipping and customer info are set, then the order transitions through states:


// Set checkout details
await orderService.setShippingAddress(orderId, address);
await orderService.setCustomerEmail(orderId, email);
await orderService.updateTotals(orderId);
 
// Transition to payment
await orderService.transitionState(orderId, "payment_pending");

State Transitions


await orderService.transitionState(orderId, "payment_pending");
await orderService.transitionState(orderId, "paid");
await orderService.transitionState(orderId, "shipped");
await orderService.transitionState(orderId, "delivered");
await orderService.transitionState(orderId, "cancelled");

Order Lines

Each order contains line items:


order.lines = [
	{
		variantId: 456,
		variant: { sku: "SHIRT-M", name: "Blue Shirt - Medium" },
		quantity: 2,
		unitPrice: 2999,
		total: 5998
	}
];

Order Code

Orders have a human-readable code:


// Lookup by code
const order = await orderService.getByCode("ORD-2024-00001");

Guest Orders

Orders can be placed without an account. Guest orders use cartToken for identification and store an email address directly on the order.