Commerce Orders Skill

Domain knowledge for order management and fulfillment operations.

Order Lifecycle

Status Flow

         ┌─────────────────────────────────────┐
         │                                     │
         ▼                                     │
    [pending] ──► [confirmed] ──► [processing] │
         │              │              │       │
         │              │              ▼       │
         │              │         [shipped] ───┤
         │              │              │       │
         │              │              ▼       │
         │              │        [delivered]   │
         │              │                      │
         └──────────────┴──► [cancelled] ◄─────┘
                             [refunded]

Status Definitions

Payment Status

Fulfillment Status

Order Structure

{
  id: "uuid",
  orderNumber: "ORD-12345",
  customerId: "customer-uuid",

  // Status
  status: "pending",
  paymentStatus: "paid",
  fulfillmentStatus: "unfulfilled",

  // Amounts
  totalAmount: 89.97,
  currency: "USD",

  // Items
  items: [
    {
      id: "item-uuid",
      sku: "WIDGET-001",
      name: "Premium Widget",
      quantity: 3,
      unitPrice: 29.99,
      total: 89.97
    }
  ],

  // Shipping
  shippingAddress: { ... },
  trackingNumber: "FEDEX123",

  // Metadata
  notes: "Gift wrap requested",
  createdAt: "2024-01-15T10:30:00Z",
  updatedAt: "2024-01-15T10:30:00Z"
}

Order Number Format

Default format: ORD-{sequence}

Examples:

• ORD-1
• ORD-12345
• ORD-1000000

Common Operations

Create Order

Required:

• customerId - Customer UUID
• items - At least one item with sku, name, quantity, unitPrice

Optional:

• currency - Default USD
• notes - Order notes

Update Status

Valid transitions only:

• pending → confirmed, cancelled
• confirmed → processing, cancelled
• processing → shipped
• shipped → delivered

Ship Order

Requires:

• Order in processing status
• Optional tracking number

Sets:

• status → shipped
• fulfillmentStatus → fulfilled
• trackingNumber

Cancel Order

Allowed for:

• pending orders
• confirmed orders
• processing orders (with inventory release)

Not allowed for:

• shipped orders (use return instead)
• delivered orders (use return instead)

Order Events

Best Practices

1. Validate before create - Check customer exists, items valid
2. Reserve inventory - Hold stock when order placed
3. Confirm payment - Wait for payment before processing
4. Track everything - Always add tracking numbers
5. Handle failures - Release inventory on cancel

Common Errors

Shipping Integration

Tracking Number Format

Varies by carrier:

• FedEx: 12-22 characters
• UPS: 1Z + 16 alphanumeric
• USPS: 20-22 digits
• DHL: 10 digits

Setting Tracking

ship_order({
  orderId: "uuid",
  trackingNumber: "FEDEX123456789"
})