Orders API

Overview

The Orders API manages order creation, status tracking, and fulfillment. Returns OrderInstance objects with direct property access.

import { Orders, OrderStatus } from 'lua-cli';

// Create order - returns OrderInstance
const order = await Orders.create({
  basketId: 'basket_abc123',
  data: { shippingAddress, paymentMethod }
});

// Direct property access
console.log(order.status);       // "pending"
console.log(order.totalAmount);  // 59.98
console.log(order.items);        // Array of items

// Instance methods
await order.updateStatus(OrderStatus.FULFILLED);
await order.update({ trackingNumber: 'ABC123' });
await order.save();

// Access updated properties
console.log(order.status);          // "fulfilled"
console.log(order.trackingNumber);  // "ABC123"

Direct Access

Access order.status not order.common.status

Instance Methods

Built-in updateStatus(), update(), and save() methods

Auto-Sync

Properties update after method calls

Type-Safe

Full TypeScript support

Order Statuses

import { OrderStatus } from 'lua-cli';

PENDING

Order created, not yet confirmedInitial status for new orders

CONFIRMED

Order confirmed, being processedPayment successful, ready for fulfillment

FULFILLED

Order completed and deliveredFinal status for successful orders

CANCELLED

Order cancelled by user or systemNo further processing

Methods

create()

Create a new order.

Orders.create(orderData: CreateOrderRequest): Promise<OrderInstance>

orderData.basketId

string

required

ID of the basket to convert to order

orderData.data

object

required

Order details (shipping, payment, etc.)

Returns: OrderInstance with direct property access and methods Example:

const order = await Orders.create({
  basketId: 'basket_abc123',
  data: {
    shippingAddress: {
      street: '123 Main St',
      city: 'New York',
      zip: '10001'
    },
    paymentMethod: 'stripe',
    customerEmail: '[email protected]'
  }
});

// Direct property access
console.log(order.id);          // "order_def456"
console.log(order.status);      // "pending"
console.log(order.totalAmount); // 59.98
console.log(order.items);       // Array of items
console.log(order.shippingAddress.city); // "New York"

// Instance methods available
await order.updateStatus(OrderStatus.CONFIRMED);

get()

Retrieve orders, optionally filtered by status.

Orders.get(status?: OrderStatus): Promise<OrderInstance[]>

Examples:

// Get all orders
const allOrders = await Orders.get();

// Get pending orders only
const pending = await Orders.get(OrderStatus.PENDING);

// Get fulfilled orders
const fulfilled = await Orders.get(OrderStatus.FULFILLED);

getById()

Get a specific order by ID.

Orders.getById(orderId: string): Promise<OrderInstance>

Returns: OrderInstance with direct property access Example:

const order = await Orders.getById('order_def456');

// Direct property access (no .common needed!)
console.log(order.status);       // "fulfilled"
console.log(order.totalAmount);  // 59.98
console.log(order.items);        // Array of items
console.log(order.shippingAddress); // Address object

// Instance methods
await order.updateStatus(OrderStatus.FULFILLED);
await order.update({ deliveryDate: '2025-10-15' });

updateStatus()

Update order status.

Orders.updateStatus(status: OrderStatus, orderId: string): Promise<OrderResponse>

Or use instance method:

order.updateStatus(status: OrderStatus): Promise<OrderInstance>

Returns: OrderInstance with updated status Example:

// Using static method
const order = await Orders.updateStatus(OrderStatus.CONFIRMED, orderId);

// Or using instance method (recommended)
await order.updateStatus(OrderStatus.CONFIRMED);
await order.updateStatus(OrderStatus.FULFILLED);
await order.updateStatus(OrderStatus.FULFILLED);

// Access updated status directly
console.log(order.status); // "fulfilled"

// Cancel order
await order.updateStatus(OrderStatus.CANCELLED);

updateData()

Update order data/metadata.

Orders.updateData(data: Record<string, any>, orderId: string): Promise<OrderResponse>

Example:

await Orders.updateData({
  trackingNumber: 'TRACK123456',
  carrier: 'UPS',
  estimatedDelivery: '2025-10-10',
  notes: 'Fragile - handle with care'
}, orderId);

save() (Instance Method)

Save the current state of the order to the server. This is a convenience method that persists all changes made to the order instance.

order.save(): Promise<boolean>

Returns: Promise resolving to true if successful Example:

const order = await Orders.getById('order_def456');

// Modify order data properties
order.trackingNumber = 'TRACK123456';
order.carrier = 'UPS';
order.estimatedDelivery = '2025-10-10';

// Save all changes at once
await order.save();

// Much cleaner workflow!

New in Latest Version: The save() method provides a simpler workflow - modify properties then save, rather than calling Orders.updateData() with the order ID.

OrderInstance

All order methods return OrderInstance objects with: Direct Property Access:

order.id
order.status          // No .common needed!
order.totalAmount     // Direct access
order.itemCount       // Direct access
order.items           // Array of items
order.currency
order.shippingAddress // Data property via proxy
order.paymentMethod   // Data property via proxy
order.createdAt       // Via proxy (from OrderData)

Instance Methods:

await order.updateStatus(OrderStatus.FULFILLED);
await order.update({ trackingNumber: 'ABC123' });
await order.save();

Backward Compatible:

order.status;         // ✅ New way
order.common.status;  // ✅ Old way still works

Complete Examples

Create Order Tool

import { LuaTool, Orders } from 'lua-cli';
import { z } from 'zod';

export class CreateOrderTool implements LuaTool {
  name = "create_order";
  description = "Create order from basket";
  
  inputSchema = z.object({
    basketId: z.string(),
    shippingAddress: z.object({
      street: z.string(),
      city: z.string(),
      zip: z.string()
    }),
    paymentMethod: z.string().default('stripe')
  });

  async execute(input: z.infer<typeof this.inputSchema>) {
    const order = await Orders.create({
      basketId: input.basketId,
      data: {
        shippingAddress: input.shippingAddress,
        paymentMethod: input.paymentMethod
      }
    });
    
    return {
      orderId: order.id,
      status: order.common.status,
      total: `$${order.common.totalAmount.toFixed(2)}`,
      message: "Order created successfully!"
    };
  }
}

Track Order Tool

export class TrackOrderTool implements LuaTool {
  name = "track_order";
  description = "Get order status and tracking info";
  
  inputSchema = z.object({
    orderId: z.string()
  });

  async execute(input: z.infer<typeof this.inputSchema>) {
    const order = await Orders.getById(input.orderId);
    
    return {
      orderId: order.id,
      status: order.common.status,
      total: `$${order.common.totalAmount.toFixed(2)}`,
      itemCount: order.common.itemCount,
      trackingNumber: order.data?.trackingNumber,
      estimatedDelivery: order.data?.estimatedDelivery,
      message: this.getStatusMessage(order.common.status)
    };
  }
  
  private getStatusMessage(status: string): string {
    switch (status) {
      case 'pending': return 'Order is being processed';
      case 'confirmed': return 'Order confirmed and being prepared';
      case 'fulfilled': return 'Order delivered!';
      case 'cancelled': return 'Order was cancelled';
      default: return 'Unknown status';
    }
  }
}

Update Order Status Tool

export class UpdateOrderStatusTool implements LuaTool {
  name = "update_order_status";
  description = "Update order fulfillment status";
  
  inputSchema = z.object({
    orderId: z.string(),
    status: z.enum(['pending', 'confirmed', 'fulfilled', 'cancelled'])
  });

  async execute(input: z.infer<typeof this.inputSchema>) {
    const statusMap = {
      'pending': OrderStatus.PENDING,
      'confirmed': OrderStatus.CONFIRMED,
      'fulfilled': OrderStatus.FULFILLED,
      'cancelled': OrderStatus.CANCELLED
    };
    
    await Orders.updateStatus(statusMap[input.status], input.orderId);
    
    return {
      success: true,
      message: `Order status updated to ${input.status}`
    };
  }
}

Use Cases

Order Fulfillment Workflow

// 1. Create order
const order = await Orders.create({ basketId, data });

// 2. Confirm payment
await Orders.updateStatus(OrderStatus.CONFIRMED, order.id);

// 3. Add tracking info
await Orders.updateData({
  trackingNumber: 'TRACK123',
  carrier: 'UPS',
  shippedAt: new Date().toISOString()
}, order.id);

// 4. Mark as delivered
await Orders.updateStatus(OrderStatus.FULFILLED, order.id);

Customer Service Lookup

// Find customer's orders
const userOrders = await Orders.get();

// Filter recent orders
const recent = userOrders.filter(order => {
  const orderDate = new Date(order.createdAt);
  const thirtyDaysAgo = new Date();
  thirtyDaysAgo.setDate(thirtyDaysAgo.getDate() - 30);
  return orderDate > thirtyDaysAgo;
});

Order Analytics

// Get all orders
const orders = await Orders.get();

// Calculate metrics
const totalRevenue = orders.reduce((sum, order) => 
  sum + order.common.totalAmount, 0
);

const avgOrderValue = totalRevenue / orders.length;

const fulfillmentRate = orders.filter(o => 
  o.common.status === OrderStatus.FULFILLED
).length / orders.length;

Best Practices

Store Tracking Information

await Orders.updateData({
  trackingNumber: 'TRACK123456',
  carrier: 'UPS',
  trackingUrl: 'https://track.ups.com/...',
  estimatedDelivery: '2025-10-10'
}, orderId);

Send Status Notifications

async updateOrderStatus(orderId: string, status: OrderStatus) {
  // Update status
  await Orders.updateStatus(status, orderId);
  
  // Send notification
  const order = await Orders.getById(orderId);
  await sendEmail(order.data.customerEmail, {
    subject: `Order ${orderId} - ${status}`,
    body: getEmailTemplate(status, order)
  });
}

Handle Cancellations Gracefully

async cancelOrder(orderId: string, reason: string) {
  const order = await Orders.getById(orderId);
  
  // Can only cancel if not fulfilled
  if (order.common.status === OrderStatus.FULFILLED) {
    throw new Error('Cannot cancel fulfilled order');
  }
  
  // Update status and add reason
  await Orders.updateStatus(OrderStatus.CANCELLED, orderId);
  await Orders.updateData({
    cancellationReason: reason,
    cancelledAt: new Date().toISOString()
  }, orderId);
}

Validate Order Exists

const order = await Orders.getById(orderId);

if (!order) {
  throw new Error(`Order not found: ${orderId}`);
}

Getting Started

Core Concepts

CLI Commands

API Reference

Template & Examples

Overview

Direct Access

Instance Methods

Auto-Sync

Type-Safe

Order Statuses

Methods

create()

get()

getById()

updateStatus()

updateData()

save() (Instance Method)

OrderInstance

Complete Examples

Create Order Tool

Track Order Tool

Update Order Status Tool

Use Cases

Order Fulfillment Workflow

Customer Service Lookup

Order Analytics

Best Practices

Next Steps

Baskets API

Order Examples

Getting Started

Core Concepts

CLI Commands

API Reference

Template & Examples

Documentation Index

​Overview

Direct Access

Instance Methods

Auto-Sync

Type-Safe

​Order Statuses

​Methods

​create()

​get()

​getById()

​updateStatus()

​updateData()

​save() (Instance Method)

​OrderInstance

​Complete Examples

​Create Order Tool

​Track Order Tool

​Update Order Status Tool

​Use Cases

​Order Fulfillment Workflow

​Customer Service Lookup

​Order Analytics

​Best Practices

​Next Steps

Baskets API

Order Examples

Overview

Order Statuses

Methods

create()

get()

getById()

updateStatus()

updateData()

save() (Instance Method)

OrderInstance

Complete Examples

Create Order Tool

Track Order Tool

Update Order Status Tool

Use Cases

Order Fulfillment Workflow

Customer Service Lookup

Order Analytics

Best Practices

Next Steps