Order Management

Overview

Sales Orders in the SynthesQ CRM/ERP system represent customer purchase requests and form the foundation of the order-to-cash workflow. Orders track all aspects of a sale from creation through completion, including line items, pricing, customer information, and fulfillment status.

Order Structure

Core Order Fields

Each order contains the following essential information:

Order Identity:

order_number - Unique identifier (e.g., "ORD-A3X7K9M2")
id - Internal database ID
order_date - Date order was placed
due_date - Expected completion/delivery date

Customer Information:

customer_id - Reference to customer record
billing_address - Customer billing address details
shipping_info - Shipping address and delivery instructions

Financial Details:

subtotal_amount - Sum of all line items before taxes/fees
tax_amount - Total tax charged
shipping_amount - Shipping and handling charges
discount_amount - Any discounts applied
total_amount - Final order total (calculated automatically)
currency - Currency code (default: USD)

Business Context:

sales_rep_id - Assigned sales representative
source - Order origin (online_store, manual, phone, email, api)
priority - Order priority level (low, normal, high, urgent)
quote_id - Reference to related quote (if applicable)
opportunity_id - Reference to CRM opportunity (if applicable)

Status Tracking:

status - Current order status
confirmed_at - When order was confirmed
shipped_at - When order was shipped
delivered_at - When order was delivered
cancelled_at - When order was cancelled (if applicable)

Additional Fields:

payment_terms - Payment terms and conditions
notes - Internal notes about the order
custom_fields - Extensible JSON field for custom data
tags - Array of tags for organization

Order Line Items

Each order contains one or more line items representing products/services:

json

{
  "id": 456,
  "order_id": 123,
  "product_id": 789,
  "sku": "WIDGET-001",
  "name": "Premium Widget",
  "description": "High-quality widget with advanced features",
  "quantity": 5,
  "unit_price": 99.99,
  "tax_amount": 12.50,
  "discount_amount": 10.00,
  "line_total": 502.45,
  "notes": "Customer requested expedited production"
}

Order Status Lifecycle

Orders progress through a defined set of statuses:

Draft

Description: Initial state when order is created but not yet submitted

Characteristics:

Can be freely edited
Not visible to customer
No inventory reservations made
Can be deleted without audit trail

Transitions: → Pending, Confirmed

Pending

Description: Order submitted and awaiting confirmation

Characteristics:

Customer notified
Awaiting payment or approval
Limited editing allowed
Inventory may be reserved

Transitions: → Confirmed, Cancelled, On Hold

Confirmed

Description: Order approved and ready for fulfillment

Characteristics:

Payment authorized or received
Inventory reserved
Fulfillment team notified
Cannot be easily modified

Transitions: → Processing, Cancelled

Processing

Description: Order being prepared for shipment

Characteristics:

Items being picked/packed
Inventory actively allocated
Shipping label may be generated
Customer notified of progress

Transitions: → Shipped, On Hold, Cancelled

Shipped

Description: Order dispatched to customer

Characteristics:

All items shipped
Tracking number assigned
Customer notified with tracking info
Cannot be cancelled (must be returned)

Transitions: → Delivered, Completed

Delivered

Description: Order received by customer

Characteristics:

Delivery confirmed
Customer signature obtained (if required)
Ready for completion
Return period begins

Transitions: → Completed

Completed

Description: Order fully fulfilled and closed

Characteristics:

All items delivered and accepted
Payment received
Invoice generated and sent
No further action required

Transitions: Terminal state

Cancelled

Description: Order cancelled before completion

Characteristics:

cancellation_reason required
Inventory reservations released
Customer notified
Cannot be reactivated

Transitions: Terminal state

On Hold

Description: Order temporarily paused

Characteristics:

Used for payment issues, stock problems, or customer requests
Can be resumed to previous status
Inventory reservations maintained
Customer notified of hold status

Transitions: → Any previous status, Cancelled

Creating Orders

Basic Order Creation

Endpoint: POST /api/v1/sales/orders

Authentication: Required (Bearer token)

Request Body:

json

{
  "customer_id": 42,
  "order_date": "2025-12-17",
  "due_date": "2025-12-24",
  "source": "online_store",
  "priority": "normal",
  "currency": "USD",
  "billing_address": {
    "street": "123 Main St",
    "city": "San Francisco",
    "state": "CA",
    "postal_code": "94105",
    "country": "US"
  },
  "shipping_info": {
    "method": "standard",
    "street": "123 Main St",
    "city": "San Francisco",
    "state": "CA",
    "postal_code": "94105",
    "country": "US",
    "instructions": "Leave at front door"
  },
  "payment_terms": {
    "method": "credit_card",
    "terms": "Net 30",
    "due_days": 30
  },
  "items": [
    {
      "product_id": 101,
      "quantity": 2,
      "unit_price": 99.99,
      "tax_amount": 5.00,
      "discount_amount": 0
    },
    {
      "product_id": 102,
      "quantity": 1,
      "unit_price": 149.99,
      "tax_amount": 7.50,
      "discount_amount": 15.00
    }
  ],
  "notes": "Customer is VIP - prioritize fulfillment"
}

Response (201 Created):

json

{
  "message": "Order created successfully",
  "data": {
    "id": 123,
    "order_number": "ORD-A3X7K9M2",
    "status": "draft",
    "customer": {
      "id": 42,
      "customer_number": "CUST-00042",
      "company_name": "Acme Corporation",
      "email": "orders@acme.com"
    },
    "sales_rep": null,
    "order_date": "2025-12-17",
    "due_date": "2025-12-24",
    "source": "online_store",
    "priority": "normal",
    "subtotal_amount": 349.97,
    "tax_amount": 12.50,
    "shipping_amount": 0.00,
    "discount_amount": 15.00,
    "total_amount": 347.47,
    "currency": "USD",
    "items": [
      {
        "id": 456,
        "product_id": 101,
        "sku": "WIDGET-001",
        "name": "Premium Widget",
        "quantity": 2,
        "unit_price": 99.99,
        "tax_amount": 5.00,
        "discount_amount": 0.00,
        "line_total": 204.98
      },
      {
        "id": 457,
        "product_id": 102,
        "sku": "GADGET-002",
        "name": "Smart Gadget",
        "quantity": 1,
        "unit_price": 149.99,
        "tax_amount": 7.50,
        "discount_amount": 15.00,
        "line_total": 142.49
      }
    ],
    "billing_address": {
      "street": "123 Main St",
      "city": "San Francisco",
      "state": "CA",
      "postal_code": "94105",
      "country": "US"
    },
    "shipping_info": {
      "method": "standard",
      "street": "123 Main St",
      "city": "San Francisco",
      "state": "CA",
      "postal_code": "94105",
      "country": "US",
      "instructions": "Leave at front door"
    },
    "confirmed_at": null,
    "shipped_at": null,
    "delivered_at": null,
    "cancelled_at": null,
    "created_at": "2025-12-17T10:30:00Z",
    "updated_at": "2025-12-17T10:30:00Z"
  }
}

Order Validation

The system validates orders during creation:

Required Fields:

customer_id - Must reference valid customer
items - At least one line item required
Each item must have: product_id or (name and sku), quantity, unit_price

Automatic Calculations:

subtotal_amount - Sum of all line item totals
total_amount - Subtotal + tax + shipping - discount
Line item line_total - (unit_price × quantity) + tax - discount

Business Rules:

quantity must be positive
unit_price must be non-negative
due_date should be after order_date
Product inventory checked if track_inventory is enabled

Listing Orders

Get All Orders

Endpoint: GET /api/v1/sales/orders

Authentication: Required (Bearer token)

Query Parameters:

status (string) - Filter by status (draft, pending, confirmed, etc.)
customer_id (integer) - Filter by customer
sales_rep_id (integer) - Filter by sales representative
source (string) - Filter by source (online_store, manual, phone, email, api)
priority (string) - Filter by priority (low, normal, high, urgent)
from_date (date) - Filter by order_date >= this date
to_date (date) - Filter by order_date <= this date
min_total (number) - Filter by total_amount >= this value
max_total (number) - Filter by total_amount <= this value
search (string) - Search order number, customer name/email
sort_by (string) - Sort field (order_date, total_amount, status, due_date)
sort_direction (string) - Sort direction (asc, desc)
page (integer) - Page number for pagination
per_page (integer) - Items per page (default: 25, max: 100)

Example Request:

bash

GET /api/v1/sales/orders?status=confirmed&from_date=2025-12-01&sort_by=order_date&sort_direction=desc&per_page=50

Response (200 OK):

json

{
  "data": [
    {
      "id": 123,
      "order_number": "ORD-A3X7K9M2",
      "status": "confirmed",
      "customer": {
        "id": 42,
        "customer_number": "CUST-00042",
        "company_name": "Acme Corporation"
      },
      "order_date": "2025-12-17",
      "due_date": "2025-12-24",
      "total_amount": 347.47,
      "currency": "USD",
      "confirmed_at": "2025-12-17T11:00:00Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 50,
    "total": 1,
    "last_page": 1,
    "from": 1,
    "to": 1
  },
  "links": {
    "first": "/api/v1/sales/orders?page=1",
    "last": "/api/v1/sales/orders?page=1",
    "prev": null,
    "next": null
  }
}

Retrieving Order Details

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

Authentication: Required (Bearer token)

Response (200 OK):

json

{
  "data": {
    "id": 123,
    "order_number": "ORD-A3X7K9M2",
    "status": "confirmed",
    "customer": {
      "id": 42,
      "customer_number": "CUST-00042",
      "company_name": "Acme Corporation",
      "email": "orders@acme.com",
      "phone": "+1-555-0100"
    },
    "sales_rep": {
      "id": 5,
      "name": "Jane Smith",
      "email": "jane.smith@company.com"
    },
    "order_date": "2025-12-17",
    "due_date": "2025-12-24",
    "source": "online_store",
    "priority": "normal",
    "subtotal_amount": 349.97,
    "tax_amount": 12.50,
    "shipping_amount": 0.00,
    "discount_amount": 15.00,
    "total_amount": 347.47,
    "currency": "USD",
    "items": [
      {
        "id": 456,
        "product_id": 101,
        "sku": "WIDGET-001",
        "name": "Premium Widget",
        "description": "High-quality widget",
        "quantity": 2,
        "unit_price": 99.99,
        "tax_amount": 5.00,
        "discount_amount": 0.00,
        "line_total": 204.98
      },
      {
        "id": 457,
        "product_id": 102,
        "sku": "GADGET-002",
        "name": "Smart Gadget",
        "description": "Advanced smart gadget",
        "quantity": 1,
        "unit_price": 149.99,
        "tax_amount": 7.50,
        "discount_amount": 15.00,
        "line_total": 142.49
      }
    ],
    "billing_address": {
      "street": "123 Main St",
      "city": "San Francisco",
      "state": "CA",
      "postal_code": "94105",
      "country": "US"
    },
    "shipping_info": {
      "method": "standard",
      "street": "123 Main St",
      "city": "San Francisco",
      "state": "CA",
      "postal_code": "94105",
      "country": "US",
      "instructions": "Leave at front door"
    },
    "payment_terms": {
      "method": "credit_card",
      "terms": "Net 30",
      "due_days": 30
    },
    "confirmed_at": "2025-12-17T11:00:00Z",
    "shipped_at": null,
    "delivered_at": null,
    "cancelled_at": null,
    "notes": "Customer is VIP - prioritize fulfillment",
    "created_at": "2025-12-17T10:30:00Z",
    "updated_at": "2025-12-17T11:00:00Z"
  }
}

Updating Orders

Endpoint: PUT /api/v1/sales/orders/{order}

Authentication: Required (Bearer token)

Update Constraints:

Draft orders: Full editing allowed
Pending/Confirmed orders: Limited fields can be updated
Processing/Shipped/Delivered orders: Very limited updates
Completed/Cancelled orders: No updates allowed

Request Body (partial updates supported):

json

{
  "priority": "urgent",
  "due_date": "2025-12-22",
  "shipping_info": {
    "method": "express",
    "instructions": "Call customer upon arrival"
  },
  "notes": "Customer called - needs urgent delivery"
}

Response (200 OK):

json

{
  "message": "Order updated successfully",
  "data": {
    "id": 123,
    "order_number": "ORD-A3X7K9M2",
    "priority": "urgent",
    "due_date": "2025-12-22",
    "updated_at": "2025-12-17T14:30:00Z"
  }
}

Searching Orders

Endpoint: GET /api/v1/sales/orders/search

Authentication: Required (Bearer token)

Query Parameters:

q (string, required) - Search query
status (string) - Filter by status
date_from (date) - Filter orders from this date
date_to (date) - Filter orders until this date
per_page (integer) - Results per page

Search Fields:

Order number
Customer name
Customer email
Customer company name
Customer number
Order notes

Example Request:

bash

GET /api/v1/sales/orders/search?q=acme&status=confirmed

Response (200 OK):

json

{
  "data": [
    {
      "id": 123,
      "order_number": "ORD-A3X7K9M2",
      "status": "confirmed",
      "customer": {
        "id": 42,
        "customer_number": "CUST-00042",
        "company_name": "Acme Corporation"
      },
      "total_amount": 347.47,
      "order_date": "2025-12-17"
    }
  ],
  "meta": {
    "total": 1,
    "per_page": 25,
    "current_page": 1
  }
}

Orders Requiring Attention

Endpoint: GET /api/v1/sales/orders/requires-attention

Authentication: Required (Bearer token)

Returns: Orders that need immediate action:

Orders overdue (past due_date)
Orders due within 1 day
Orders in pending_approval status
Orders on_hold status

Response (200 OK):

json

{
  "data": [
    {
      "id": 123,
      "order_number": "ORD-A3X7K9M2",
      "status": "pending",
      "customer": {
        "id": 42,
        "company_name": "Acme Corporation"
      },
      "total_amount": 347.47,
      "due_date": "2025-12-18",
      "days_until_due": 1,
      "is_overdue": false,
      "is_urgent": true,
      "reason": "Due within 1 day"
    }
  ],
  "meta": {
    "total_attention_required": 1,
    "overdue_count": 0,
    "urgent_count": 1
  }
}

High-Value Orders

Endpoint: GET /api/v1/sales/orders/high-value

Authentication: Required (Bearer token)

Query Parameters:

minimum_amount (number) - Minimum order total (default: 10000)
status (string) - Filter by status
from_date (date) - Filter from date
to_date (date) - Filter to date

Example Request:

bash

GET /api/v1/sales/orders/high-value?minimum_amount=5000&status=confirmed

Response (200 OK):

json

{
  "data": [
    {
      "id": 125,
      "order_number": "ORD-B7Y9L2K5",
      "status": "confirmed",
      "customer": {
        "id": 45,
        "company_name": "Enterprise Corp"
      },
      "total_amount": 12450.00,
      "currency": "USD",
      "order_date": "2025-12-17",
      "is_high_value": true
    }
  ],
  "meta": {
    "total": 1,
    "total_value": 12450.00,
    "average_value": 12450.00
  }
}

Business Scenarios

Scenario 1: Creating Order from Quote

When a customer accepts a quote, convert it to an order:

Retrieve quote details: GET /api/v1/sales/quotes/{quote_id}
Create order with quote reference:

json

{
  "customer_id": 42,
  "quote_id": 789,
  "items": [/* items from quote */],
  "billing_address": {/* from quote */},
  "notes": "Converted from Quote Q-789"
}

Update quote status to "converted"

Scenario 2: Bulk Order Creation

For wholesale customers or recurring orders:

Prepare order template with common items
Submit orders via API with customer-specific details
Use source: "api" to track automated orders
Set priority: "normal" unless specified otherwise

Scenario 3: Order with Custom Pricing

When special pricing is negotiated:

Create order with custom unit_price for items
Add discount_amount at line item or order level
Include reason in notes field
Require approval if discount exceeds threshold

Scenario 4: International Orders

For orders shipping internationally:

Set appropriate currency (e.g., "EUR", "GBP")
Include customs information in shipping_info
Calculate appropriate tax_amount based on destination
Allow longer due_date for international shipping

Integration Points

With CRM Module

Orders linked to customers via customer_id
Can reference opportunities (opportunity_id) for sales tracking
Customer activities tracked with order events

With Operations Module

Product inventory reserved when order confirmed
Stock allocated during order processing
Inventory decremented when order shipped
Product availability checked during order creation

With Finance Module

Orders generate accounts receivable
Revenue recognition triggered on order completion
Tax calculations integrated with tax engine
Payment tracking linked to invoices

Best Practices

Always Validate Customer Data: Ensure customer exists and has complete contact information before creating orders
Set Realistic Due Dates: Consider product availability, shipping method, and customer location
Use Order Source Tracking: Tag orders with appropriate source to analyze channel performance
Leverage Priority Levels: Use priority flags to help fulfillment teams prioritize work
Include Detailed Notes: Document special instructions, customer requests, or unusual circumstances
Monitor Orders Requiring Attention: Check this endpoint daily to prevent missed deadlines
Track High-Value Orders: Give special attention to large orders to ensure customer satisfaction
Use Search Effectively: Utilize search endpoint to quickly locate orders by customer or order number

Order Workflow - Order confirmation, fulfillment, and completion processes
Invoice Generation - Creating invoices from orders
Payment Processing - Processing payments for orders
Order-to-Cash Workflow - Complete order-to-cash process

Order Management ​

Overview ​

Order Structure ​

Core Order Fields ​

Order Line Items ​

Order Status Lifecycle ​

Draft ​

Pending ​

Confirmed ​

Processing ​

Shipped ​

Delivered ​

Completed ​

Cancelled ​

On Hold ​

Creating Orders ​

Basic Order Creation ​

Order Validation ​

Listing Orders ​

Get All Orders ​

Retrieving Order Details ​

Updating Orders ​

Searching Orders ​

Orders Requiring Attention ​

High-Value Orders ​

Business Scenarios ​

Scenario 1: Creating Order from Quote ​

Scenario 2: Bulk Order Creation ​

Scenario 3: Order with Custom Pricing ​

Scenario 4: International Orders ​

Integration Points ​

With CRM Module ​

With Operations Module ​

With Finance Module ​

Best Practices ​

Related Guides ​

Order Management

Overview

Order Structure

Core Order Fields

Order Line Items

Order Status Lifecycle

Draft

Pending

Confirmed

Processing

Shipped

Delivered

Completed

Cancelled

On Hold

Creating Orders

Basic Order Creation

Order Validation

Listing Orders

Get All Orders

Retrieving Order Details

Updating Orders

Searching Orders

Orders Requiring Attention

High-Value Orders

Business Scenarios

Scenario 1: Creating Order from Quote

Scenario 2: Bulk Order Creation

Scenario 3: Order with Custom Pricing

Scenario 4: International Orders

Integration Points

With CRM Module

With Operations Module

With Finance Module

Best Practices

Related Guides