Orders Module

Order Status Flow

API Endpoints

# List orders with filtering
GET /api/v1/orders?status=pending&payment_status=paid&per_page=20

# Create an order
POST /api/v1/orders
{
  "customer_id": "uuid",
  "items": [
    { "product_id": "uuid", "quantity": 2, "unit_price": 999.00 }
  ],
  "shipping_address_id": "uuid",
  "payment_method": "cod",
  "notes": "Gift wrap requested"
}

# Get an order
GET /api/v1/orders/{id}

# Update an order
PATCH /api/v1/orders/{id}

# Delete an order
DELETE /api/v1/orders/{id}

# Update order status
PATCH /api/v1/orders/{id}/status
{
  "status": "confirmed",
  "reason": "Payment verified"
}

# Bulk status update
POST /api/v1/orders/bulk/status
{
  "order_ids": ["uuid-1", "uuid-2"],
  "status": "ready_to_ship"
}

# Get order statistics
GET /api/v1/orders/stats/summary

TypeScript Types

interface Order {
  id: string;
  order_number: string;
  external_id: string | null;
  source_module: string;

  // Customer
  customer_id: string;
  customer?: Customer;

  // Status
  status: OrderStatus;
  payment_status: PaymentStatus;
  fulfillment_status: string;

  // Items
  items: OrderItem[];

  // Pricing
  subtotal: number;
  tax: number;
  discount: number;
  shipping_cost: number;
  total: number;
  currency: string;

  // Addresses
  billing_address?: CustomerAddress;
  shipping_address?: CustomerAddress;

  // Metadata
  notes: string | null;
  tags: string[];

  created_at: string;
  updated_at: string;
}

type OrderStatus =
  | 'pending'
  | 'confirmed'
  | 'processing'
  | 'ready_to_ship'
  | 'shipped'
  | 'out_for_delivery'
  | 'delivered'
  | 'cancelled'
  | 'failed'
  | 'rto_initiated'
  | 'rto_received';

type PaymentStatus =
  | 'pending'
  | 'paid'
  | 'partially_paid'
  | 'refunded'
  | 'failed';

interface OrderItem {
  id: string;
  product_id: string;
  variant_id: string | null;
  sku: string;
  name: string;
  quantity: number;
  unit_price: number;
  tax: number;
  discount: number;
  total: number;
}