Order Workflow

Overview

The order workflow in SynthesQ guides orders through a structured process from confirmation to completion. This guide covers the specialized endpoints and business processes for managing order state transitions, fulfillment operations, and completion workflows.

Table of Contents

• Order Confirmation
• Order Processing
• Order Shipping
• Order Completion
• Order Cancellation
• Order Activities
• Performance Metrics
• Bulk Operations

Order Confirmation

Confirming an Order

Endpoint: POST /api/v1/sales/orders/{order}/confirm

Authentication: Required (Bearer token)

Purpose: Transitions order from draft/pending to confirmed status, indicating payment approval and readiness for fulfillment.

Prerequisites:

• Order must be in draft or pending status
• Customer information must be complete
• Payment authorization successful (if required)
• All line items must reference valid products
• Sufficient inventory available (if tracking enabled)

Request Body:

{
  "approved_by": 5,
  "payment_authorization": "AUTH-123456",
  "notes": "Payment verified - ready for fulfillment"
}

Response (200 OK):

{
  "message": "Order confirmed successfully",
  "data": {
    "id": 123,
    "order_number": "ORD-A3X7K9M2",
    "status": "confirmed",
    "confirmed_at": "2025-12-17T11:00:00Z",
    "approved_by": 5,
    "inventory_reserved": true,
    "fulfillment_team_notified": true
  }
}

What Happens on Confirmation:

1. Order status changes to confirmed
2. confirmed_at timestamp recorded
3. Inventory reserved for order items
4. Fulfillment team receives notification
5. Order appears in fulfillment queue
6. Payment captured (if using authorize-capture flow)

Error Response (422 Unprocessable Entity):

{
  "error": "Cannot confirm order",
  "message": "Order must be in draft or pending status. Current status: processing",
  "current_status": "processing"
}

Inventory Reservation Failure:

{
  "error": "Insufficient inventory",
  "message": "Cannot confirm order due to insufficient inventory",
  "insufficient_items": [
    {
      "product_id": 101,
      "sku": "WIDGET-001",
      "name": "Premium Widget",
      "requested": 5,
      "available": 3,
      "shortage": 2
    }
  ]
}

Order Processing

Once confirmed, orders enter the processing stage where they are prepared for shipment.

Transitioning to Processing

Orders automatically transition to processing status when:

• Fulfillment team begins pick/pack operations
• Inventory is actively being allocated
• Shipping labels are generated

Manual Status Update (if needed):

PUT /api/v1/sales/orders/{order}
{
  "status": "processing",
  "notes": "Started fulfillment - picking items from warehouse"
}

Processing Activities

During processing, typical activities include:

• Warehouse picking
• Quality control checks
• Packaging
• Shipping label generation
• Customs documentation (for international orders)

Track Processing Progress via order activities:

GET /api/v1/sales/orders/{order}/activities

Order Shipping

Shipping an Order

Endpoint: POST /api/v1/sales/orders/{order}/ship

Authentication: Required (Bearer token)

Purpose: Marks order as shipped and records shipping details

Prerequisites:

• Order must be in confirmed or processing status
• All items must be packed
• Shipping label generated
• Tracking information available

Request Body:

{
  "tracking_number": "1Z999AA10123456784",
  "carrier": "UPS",
  "service_level": "Ground",
  "shipped_date": "2025-12-18",
  "estimated_delivery": "2025-12-22",
  "shipping_cost": 15.99,
  "weight": 5.2,
  "weight_unit": "lbs",
  "package_count": 1,
  "notes": "All items shipped in single package"
}

Response (200 OK):

{
  "message": "Order shipped successfully",
  "data": {
    "id": 123,
    "order_number": "ORD-A3X7K9M2",
    "status": "shipped",
    "shipped_at": "2025-12-18T14:30:00Z",
    "shipping_info": {
      "tracking_number": "1Z999AA10123456784",
      "carrier": "UPS",
      "service_level": "Ground",
      "estimated_delivery": "2025-12-22",
      "tracking_url": "https://www.ups.com/track?tracknum=1Z999AA10123456784"
    },
    "customer_notified": true,
    "notification_sent_to": "orders@acme.com"
  }
}

What Happens on Shipping:

1. Order status changes to shipped
2. shipped_at timestamp recorded
3. Tracking information stored in shipping_info
4. Customer receives shipment notification email
5. Inventory fully decremented (committed)
6. Order moves to delivery tracking phase

Error Response (422 Unprocessable Entity):

{
  "error": "Cannot ship order",
  "message": "Order must be in confirmed or processing status. Current status: pending"
}

Partial Shipments

For orders shipped in multiple packages:

First Shipment:

POST /api/v1/sales/orders/{order}/ship
{
  "tracking_number": "1Z999AA10123456784",
  "carrier": "UPS",
  "items": [
    {
      "order_item_id": 456,
      "quantity_shipped": 2
    }
  ],
  "is_partial": true,
  "notes": "Partial shipment - item 457 to follow"
}

Response includes:

{
  "status": "partially_shipped",
  "items_shipped": 1,
  "items_remaining": 1
}

Subsequent Shipments:

POST /api/v1/sales/orders/{order}/ship
{
  "tracking_number": "1Z999AA10123456785",
  "carrier": "UPS",
  "items": [
    {
      "order_item_id": 457,
      "quantity_shipped": 1
    }
  ],
  "is_final_shipment": true
}

Order Completion

Completing an Order

Endpoint: POST /api/v1/sales/orders/{order}/complete

Authentication: Required (Bearer token)

Purpose: Marks order as fully fulfilled and closed

Prerequisites:

• Order must be in shipped or delivered status
• All items delivered to customer
• Customer satisfaction confirmed (optional)
• Payment received in full (if not prepaid)

Request Body:

{
  "delivery_confirmed": true,
  "delivered_date": "2025-12-22",
  "customer_signature": "John Doe",
  "notes": "Customer confirmed receipt - no issues reported"
}

Response (200 OK):

{
  "message": "Order completed successfully",
  "data": {
    "id": 123,
    "order_number": "ORD-A3X7K9M2",
    "status": "completed",
    "delivered_at": "2025-12-22T10:15:00Z",
    "completed_at": "2025-12-22T10:15:00Z",
    "fulfillment_days": 5,
    "on_time_delivery": true,
    "customer_notified": true
  }
}

What Happens on Completion:

1. Order status changes to completed
2. delivered_at and completed_at timestamps recorded
3. Revenue recognition triggered
4. Invoice finalized (if not already generated)
5. Customer receives completion confirmation
6. Order metrics calculated and stored
7. Sales rep credited with sale
8. Order archived for historical reporting

Error Response (422 Unprocessable Entity):

{
  "error": "Cannot complete order",
  "message": "Order must be in shipped or delivered status. Current status: processing"
}

Automatic Completion

Orders may automatically complete when:

• Delivery tracking confirms successful delivery
• Customer confirms receipt via customer portal
• Specified time period passes after "delivered" status (e.g., 7 days)

Order Cancellation

Cancelling an Order

Endpoint: POST /api/v1/sales/orders/{order}/cancel

Authentication: Required (Bearer token)

Purpose: Cancels order before completion

Prerequisites:

• Order must NOT be in completed or cancelled status
• Cancellation reason required
• Customer notification recommended

Cancellation Windows:

• Draft/Pending: Can cancel freely
• Confirmed: Cancel with inventory release
• Processing: Cancel with potential restocking fee
• Shipped: Cannot cancel (must process return instead)

Request Body:

{
  "cancellation_reason": "Customer requested cancellation - found better price elsewhere",
  "refund_amount": 347.47,
  "restocking_fee": 0,
  "notify_customer": true,
  "notify_fulfillment": true
}

Response (200 OK):

{
  "message": "Order cancelled successfully",
  "data": {
    "id": 123,
    "order_number": "ORD-A3X7K9M2",
    "status": "cancelled",
    "cancelled_at": "2025-12-17T15:30:00Z",
    "cancellation_reason": "Customer requested cancellation - found better price elsewhere",
    "refund_initiated": true,
    "refund_amount": 347.47,
    "inventory_released": true,
    "customer_notified": true
  }
}

What Happens on Cancellation:

1. Order status changes to cancelled
2. cancelled_at timestamp and reason recorded
3. Reserved inventory released back to available stock
4. Payment authorization voided (if not captured)
5. Refund initiated (if payment captured)
6. Fulfillment team notified to halt processing
7. Customer receives cancellation confirmation
8. Linked invoices cancelled

Error Response (422 Unprocessable Entity):

{
  "error": "Cannot cancel order",
  "message": "Cannot cancel shipped orders. Please process a return instead.",
  "current_status": "shipped",
  "suggested_action": "create_return_order"
}

Cancellation by Status

Draft Orders:

{
  "cancellation_reason": "Order created in error",
  "notify_customer": false
}

• No inventory impact
• No refund needed
• Minimal notification required

Confirmed Orders:

{
  "cancellation_reason": "Customer cancelled before shipment",
  "refund_amount": 347.47,
  "notify_customer": true
}

• Inventory released
• Payment voided/refunded
• Customer and fulfillment notified

Processing Orders:

{
  "cancellation_reason": "Inventory shortage discovered during fulfillment",
  "refund_amount": 347.47,
  "restocking_fee": 25.00,
  "notify_customer": true
}

• Stop fulfillment immediately
• May incur restocking fee
• Partial inventory already allocated

Order Activities

Viewing Order Activities

Endpoint: GET /api/v1/sales/orders/{order}/activities

Authentication: Required (Bearer token)

Purpose: Retrieve complete activity history for an order

Response (200 OK):

{
  "data": [
    {
      "id": 789,
      "type": "order_shipped",
      "description": "Order shipped via UPS Ground",
      "user": {
        "id": 7,
        "name": "Warehouse Staff"
      },
      "metadata": {
        "tracking_number": "1Z999AA10123456784",
        "carrier": "UPS"
      },
      "created_at": "2025-12-18T14:30:00Z"
    },
    {
      "id": 788,
      "type": "order_confirmed",
      "description": "Order confirmed and ready for fulfillment",
      "user": {
        "id": 5,
        "name": "Jane Smith"
      },
      "metadata": {
        "payment_authorization": "AUTH-123456"
      },
      "created_at": "2025-12-17T11:00:00Z"
    },
    {
      "id": 787,
      "type": "order_created",
      "description": "Order created from online store",
      "user": {
        "id": null,
        "name": "System"
      },
      "metadata": {
        "source": "online_store",
        "total_amount": 347.47
      },
      "created_at": "2025-12-17T10:30:00Z"
    }
  ]
}

Activity Types:

• order_created - Order initially created
• order_updated - Order details modified
• order_confirmed - Order confirmed and approved
• order_processing - Fulfillment started
• order_shipped - Order dispatched to customer
• order_delivered - Delivery confirmed
• order_completed - Order fully fulfilled
• order_cancelled - Order cancelled
• order_on_hold - Order put on hold
• payment_received - Payment processed
• invoice_generated - Invoice created
• note_added - Internal note added
• email_sent - Email notification sent
• status_changed - Status manually changed

Performance Metrics

Order Performance Metrics

Endpoint: GET /api/v1/sales/orders/performance-metrics

Authentication: Required (Bearer token)

Query Parameters:

• from_date (date) - Start date for metrics
• to_date (date) - End date for metrics
• status (string) - Filter by order status
• sales_rep_id (integer) - Filter by sales representative

Response (200 OK):

{
  "data": {
    "period": {
      "from": "2025-12-01",
      "to": "2025-12-31"
    },
    "order_metrics": {
      "total_orders": 1247,
      "total_revenue": 1245678.90,
      "average_order_value": 998.87,
      "orders_by_status": {
        "draft": 45,
        "pending": 23,
        "confirmed": 89,
        "processing": 67,
        "shipped": 145,
        "delivered": 234,
        "completed": 589,
        "cancelled": 55
      },
      "cancellation_rate": 4.41
    },
    "fulfillment_metrics": {
      "average_fulfillment_days": 3.2,
      "on_time_delivery_rate": 94.5,
      "orders_fulfilled": 734,
      "orders_pending_fulfillment": 156,
      "fastest_fulfillment_days": 1,
      "slowest_fulfillment_days": 12
    },
    "customer_metrics": {
      "unique_customers": 567,
      "repeat_customer_rate": 38.5,
      "new_customers": 349,
      "returning_customers": 218
    },
    "top_sales_reps": [
      {
        "sales_rep_id": 5,
        "name": "Jane Smith",
        "orders": 234,
        "revenue": 289456.78,
        "average_order_value": 1236.75
      },
      {
        "sales_rep_id": 8,
        "name": "John Doe",
        "orders": 189,
        "revenue": 234567.89,
        "average_order_value": 1241.10
      }
    ]
  }
}

Bulk Operations

Bulk Order Actions

Endpoint: POST /api/v1/sales/orders/bulk-action

Authentication: Required (Bearer token)

Purpose: Perform actions on multiple orders simultaneously

Supported Actions:

• confirm - Confirm multiple orders
• cancel - Cancel multiple orders
• export - Export order data
• update_status - Update status of multiple orders
• assign_sales_rep - Assign sales representative

Request Body (Bulk Confirm):

{
  "action": "confirm",
  "order_ids": [123, 124, 125, 126],
  "parameters": {
    "approved_by": 5,
    "notes": "Bulk confirmation - daily order processing"
  }
}

Response (200 OK):

{
  "message": "Bulk action completed",
  "data": {
    "action": "confirm",
    "total_orders": 4,
    "successful": 3,
    "failed": 1,
    "results": [
      {
        "order_id": 123,
        "status": "success",
        "message": "Order confirmed"
      },
      {
        "order_id": 124,
        "status": "success",
        "message": "Order confirmed"
      },
      {
        "order_id": 125,
        "status": "success",
        "message": "Order confirmed"
      },
      {
        "order_id": 126,
        "status": "failed",
        "message": "Insufficient inventory for product WIDGET-001"
      }
    ]
  }
}

Request Body (Bulk Cancel):

{
  "action": "cancel",
  "order_ids": [127, 128],
  "parameters": {
    "cancellation_reason": "Supplier unable to fulfill - bulk cancellation",
    "notify_customers": true
  }
}

Request Body (Assign Sales Rep):

{
  "action": "assign_sales_rep",
  "order_ids": [129, 130, 131],
  "parameters": {
    "sales_rep_id": 8
  }
}

Order Invoices

Viewing Order Invoices

Endpoint: GET /api/v1/sales/orders/{order}/invoices

Authentication: Required (Bearer token)

Purpose: List all invoices associated with an order

Response (200 OK):

{
  "data": [
    {
      "id": 456,
      "invoice_number": "INV-20251217-001",
      "status": "paid",
      "total_amount": 347.47,
      "amount_paid": 347.47,
      "amount_due": 0.00,
      "issue_date": "2025-12-17",
      "due_date": "2026-01-16",
      "paid_date": "2025-12-18"
    }
  ]
}

Generating Invoice from Order

Endpoint: POST /api/v1/sales/orders/{order}/generate-invoice

Authentication: Required (Bearer token)

See Invoice Generation Guide for details.

Order Payments

Viewing Order Payments

Endpoint: GET /api/v1/sales/orders/{order}/payments

Authentication: Required (Bearer token)

Purpose: List all payments associated with an order

Response (200 OK):

{
  "data": [
    {
      "id": 789,
      "payment_number": "PAY-12345678",
      "status": "completed",
      "amount": 347.47,
      "method": "credit_card",
      "payment_date": "2025-12-18T09:15:00Z",
      "transaction_id": "TXN-987654321"
    }
  ],
  "meta": {
    "total_payments": 1,
    "total_paid": 347.47,
    "payment_status": "paid_in_full"
  }
}

Business Scenarios

Scenario 1: Standard Order Fulfillment

Complete workflow:

1. Order created: POST /api/v1/sales/orders
2. Payment processed: Order updated with payment info
3. Order confirmed: POST /api/v1/sales/orders/{order}/confirm
4. Fulfillment begins: Status automatically transitions to processing
5. Order shipped: POST /api/v1/sales/orders/{order}/ship
6. Delivery tracked: Carrier tracking updates received
7. Order completed: POST /api/v1/sales/orders/{order}/complete

Timeline: 3-5 business days (standard shipping)

Scenario 2: Rush Order Processing

Expedited workflow:

1. Order created with priority: "urgent"
2. Immediate payment capture
3. Instant confirmation: POST /api/v1/sales/orders/{order}/confirm
4. Express fulfillment: Warehouse prioritizes order
5. Same-day shipping: POST /api/v1/sales/orders/{order}/ship with express carrier
6. Next-day delivery confirmation

Timeline: 1-2 business days

Scenario 3: Backorder Management

Handling inventory shortages:

1. Order confirmed with partial inventory
2. Available items shipped immediately
3. Backordered items tracked separately
4. Customer notified of backorder status
5. Second shipment when inventory arrives
6. Order completed when all items delivered

Scenario 4: Customer-Requested Cancellation

Before shipping:

1. Customer requests cancellation
2. Verify order status: GET /api/v1/sales/orders/{order}
3. If status allows, cancel: POST /api/v1/sales/orders/{order}/cancel
4. Process refund if payment captured
5. Notify customer of cancellation confirmation

After shipping:

1. Cannot cancel - must process return
2. Create return order (separate process)
3. Customer ships items back
4. Process refund upon receipt

Integration Points

With Inventory Module

• Inventory reserved on order confirmation
• Stock decremented on order shipment
• Reservations released on order cancellation
• Low stock triggers reorder for popular items

With Finance Module

• Revenue recognized on order completion
• Accounts receivable created for unpaid orders
• Payment reconciliation with bank deposits
• Financial reporting includes order metrics

With CRM Module

• Customer purchase history updated
• Sales rep performance tracked
• Opportunity conversion recorded
• Customer satisfaction surveys triggered

Best Practices

1. Confirm Orders Promptly: Don't leave orders in pending status - confirm or cancel within 24 hours

2. Track Shipping Accurately: Always include tracking numbers and carrier information when shipping

3. Update Status in Real-Time: Keep order status current to reflect actual fulfillment state

4. Document Cancellations: Always provide detailed cancellation reasons for audit trail

5. Monitor Fulfillment Metrics: Review performance metrics weekly to identify bottlenecks

6. Use Bulk Actions Carefully: Verify order IDs before performing bulk operations

7. Communicate with Customers: Enable automatic notifications for status changes

8. Complete Orders Promptly: Mark orders complete once delivery confirmed to trigger revenue recognition

Troubleshooting

Order Won't Confirm

Possible Causes:

• Insufficient inventory
• Invalid payment authorization
• Missing required customer information
• Order already in confirmed or later status

Resolution:

• Check inventory availability
• Verify payment details
• Complete customer profile
• Review current order status

Shipping Fails

Possible Causes:

• Order not in correct status
• Missing tracking information
• Invalid carrier/service level
• Order already shipped

Resolution:

• Verify order status is confirmed or processing
• Provide complete shipping details
• Use valid carrier codes
• Check order history for previous shipments

Cannot Cancel Order

Possible Causes:

• Order already shipped
• Order completed
• Order already cancelled

Resolution:

• For shipped orders, process return instead
• Completed orders cannot be modified
• Verify current status before cancelling

Related Guides

• Order Management - Creating and managing orders
• Invoice Generation - Creating invoices from orders
• Payment Processing - Processing order payments
• Order-to-Cash Workflow - Complete end-to-end process