Orders Module

The Orders module is the heart of Auto Commerce, managing the complete order lifecycle from creation through fulfillment, returns, and analytics.

Overview

Orders in Auto Commerce:

• Multi-source: Accept orders from Shopify, WooCommerce, manual entry, or API
• State machine: Clear workflow from pending → delivered/cancelled
• Extensible: Modules can add custom data and workflows
• Automated: Trigger shipping, notifications, and fulfillment automatically

Order Lifecycle

pending → confirmed → processing → ready_to_ship → shipped
  → out_for_delivery → delivered

Alternate flows:
  → rto_initiated → rto_received (Return to Origin)
  → cancelled
  → failed

Data Model

Core Order Fields

id: UUID
external_id: string (from source platform)
source_module: string ('store-shopify', 'manual', etc.)
order_number: string (auto-generated)
status: string (see lifecycle above)
payment_status: 'pending' | 'paid' | 'failed' | 'refunded'
fulfillment_status: 'unfulfilled' | 'partial' | 'fulfilled'

customer_id: UUID
billing_address_id: UUID
shipping_address_id: UUID

subtotal: decimal
tax: decimal
discount: decimal
shipping_cost: decimal
total: decimal
currency: string (default: 'INR')

notes: text
tags: array
created_at: timestamp
updated_at: timestamp

Order Items

id: UUID
order_id: UUID
product_id: UUID
variant_id: UUID
sku: string
name: string
quantity: integer
unit_price: decimal
tax: decimal
discount: decimal
total: decimal
properties: JSON (custom line item data)

Order Metadata

Modules extend orders with custom data:

id: UUID
order_id: UUID
key: string
value: string
module_source: string

Example metadata:

• shopify_order_id: Original platform order ID
• delhivery_awb: Shipping AWB number
• whatsapp_msg_id: Confirmation message ID
• payment_transaction_id: Payment gateway reference

API Endpoints

List Orders

GET /api/v1/orders

Query Parameters:

• page, per_page: Pagination
• status: Filter by order status
• payment_status: Filter by payment status
• customer_id: Get orders for specific customer
• date_from, date_to: Date range
• search: Search by order number, customer name

Response:

{
  "data": [
    {
      "id": "uuid",
      "order_number": "ORD-2024-001",
      "status": "shipped",
      "customer": {
        "name": "John Doe",
        "email": "john@example.com"
      },
      "total": 2999.00,
      "items_count": 3,
      "created_at": "2024-01-15T10:30:00Z"
    }
  ],
  "meta": {...}
}

Get Order

GET /api/v1/orders/{id}

Returns complete order with:

• Customer details
• All line items
• Shipping information
• Payment details
• Status history
• Associated shipments

Create Order

POST /api/v1/orders

Request Body:

{
  "customer_id": "uuid",
  "items": [
    {
      "product_id": "uuid",
      "variant_id": "uuid",
      "quantity": 2,
      "unit_price": 999.00
    }
  ],
  "shipping_address": {
    "first_name": "John",
    "last_name": "Doe",
    "address1": "123 Main St",
    "city": "Mumbai",
    "state": "Maharashtra",
    "pincode": "400001",
    "phone": "+919876543210"
  },
  "notes": "Gift wrap requested"
}

Update Order Status

PATCH /api/v1/orders/{id}/status

Request Body:

{
  "status": "confirmed",
  "reason": "Payment verified"
}

Cancel Order

POST /api/v1/orders/{id}/cancel

Request Body:

{
  "reason": "Customer requested cancellation",
  "refund": true
}

Order Processing

Automatic Workflows

When an order is created:

1. Stock Reservation: Inventory reserved (not yet deducted)
2. Payment Verification: If COD, auto-confirmed; if prepaid, awaits payment
3. Confirmation: Customer notified via enabled channels
4. Shipping: When status → ready_to_ship, shipping module creates shipment
5. Notifications: Updates sent at each status change

Manual Processing

Dashboard allows:

• Bulk status updates
• Order assignment to team members
• Custom notes and tags
• Merge/split orders

Shipping Integration

Automatic Shipment Creation

// When order status → ready_to_ship
Event::dispatch(new OrderReadyToShip($order));

// Shipping module listens and creates shipment
ShippingService::createShipment($order);

NDR (Non-Delivery Report) Handling

When shipping fails:

1. NDR Created: Shipping module creates NDR case
2. Customer Contact: Auto-send WhatsApp/SMS with options
3. Action: Customer can choose:
   • Reschedule delivery
   • Change address
   • Request RTO (Return to Origin)
4. Resolution: Update order and shipment status

Payment Handling

Payment Status Flow

pending → paid → captured
        → failed
        → refunded (partial/full)

COD Orders

payment_status: 'pending'
payment_method: 'cod'

On delivery:
  payment_status → 'paid'

Prepaid Orders

payment_status: 'pending'
payment_method: 'razorpay' (or other gateway)

Payment webhook received:
  payment_status → 'paid'
  order_status → 'confirmed'

Order Analytics

Key Metrics

• Order Volume: Orders per day/week/month
• Average Order Value (AOV): Total revenue ÷ number of orders
• Conversion Rate: Orders ÷ total sessions
• Fulfillment Rate: Delivered orders ÷ total orders
• Return Rate: RTO orders ÷ delivered orders

Performance Tracking

• Average time to ship
• Average delivery time
• Customer satisfaction scores
• Payment success rate

Module Integration

Order Hooks

// Before order creation
OrderHooks::beforeCreate(function ($orderData) {
    // Validate, modify data, apply coupons
    return $orderData;
});

// After order creation
OrderHooks::afterCreate(function ($order) {
    // Send to analytics, create invoices
});

// Status change
OrderHooks::onStatusChange(function ($order, $oldStatus, $newStatus) {
    // Trigger workflows, notifications
});

Custom Order Data

// Add custom metadata
OrderService::addMetadata($orderId, 'gift_message', 'Happy Birthday!', 'gift-module');

// Read custom metadata
$giftMessage = $order->metadata('gift_message');

Best Practices

1. Always capture customer info: Email or phone required for communication
2. Use order numbers: Auto-generated, human-readable identifiers
3. Track status changes: Maintain audit trail with reasons
4. Automate where possible: Use workflows for common scenarios
5. Monitor order health: Track stuck orders, failed payments, delayed shipments

Advanced Features

Bulk Operations

POST /api/v1/orders/bulk/update-status

Update multiple orders at once.

Order Templates

Save common order configurations for quick creation.

Recurring Orders

Schedule automatic order creation (subscriptions).

Next Steps

• Products Module - Manage your product catalog
• Customers Module - Customer relationship management
• Creating Modules - Extend order functionality