A SynthesQ sales order passes through a well-defined set of statuses. Each status transition is guarded by business rules and triggers downstream automations. This guide explains every stage and the API calls that drive them.

The lifecycle at a glance

draft → confirmed → processing → shipped → delivered → closed
                ↘ cancelled

Payment is collected independently from the order status. An order can be delivered but still have an outstanding invoice - the two lifecycles are loosely coupled by design.

Stage 1: Draft

A draft order is created when a customer expresses intent to buy. Pricing is captured at creation time to lock in rates.

POST /api/v1/sales/orders
Authorization: Bearer {token}
Content-Type: application/json

{
  "customer_id": "cust_01J9RPMNVK4W",
  "currency": "USD",
  "line_items": [
    {
      "product_id": "prod_01JM5XQVZ3K7",
      "quantity": 2,
      "unit_price": 129.99
    }
  ],
  "shipping_address": {
    "line1": "123 Commerce St",
    "city": "Austin",
    "state": "TX",
    "postal_code": "78701",
    "country": "US"
  }
}

The system returns an order with status: "draft" and a generated order_number.

Stage 2: Confirmed

Confirming an order signals that both parties have agreed to the terms. Stock is reserved at this point - the stock_quantity of each variant product is decremented.

PATCH /api/v1/sales/orders/{orderId}/status
Authorization: Bearer {token}
Content-Type: application/json

{ "status": "confirmed" }

TIP

Confirm the order only after verifying stock is available. Attempting to confirm when a line item's variant has insufficient stock will return a 422 Unprocessable Entity.

Stage 3: Processing

The order moves to processing once it has been picked up by the warehouse team. This status is typically triggered by a fulfilment integration rather than a human.

Stage 4: Shipped

When the order leaves the warehouse, update with tracking information:

PATCH /api/v1/sales/orders/{orderId}/status
Authorization: Bearer {token}
Content-Type: application/json

{
  "status": "shipped",
  "tracking_number": "1Z999AA10123456784",
  "carrier": "UPS"
}

Stage 5: Delivered → Closed

Mark delivered upon carrier confirmation, then closed once any disputes or return windows have elapsed. Closing the order triggers invoice finalisation if it hasn't happened already.

Invoice and payment

An invoice is generated automatically when the order is confirmed. The invoice follows its own lifecycle: draft → issued → paid → void.

GET /api/v1/sales/invoices?order_id={orderId}

To record a payment against the invoice:

POST /api/v1/sales/payments
Authorization: Bearer {token}
Content-Type: application/json

{
  "invoice_id": "inv_01JNABCDEF",
  "amount": 259.98,
  "currency": "USD",
  "payment_method": "bank_transfer",
  "reference": "TXN-20260128-001"
}

Cancellations

An order can be cancelled from draft or confirmed only. Reserved stock is released automatically on cancellation.

PATCH /api/v1/sales/orders/{orderId}/status
Authorization: Bearer {token}
Content-Type: application/json

{ "status": "cancelled", "reason": "Customer requested cancellation" }

Useful queries

All open orders for a customer:

GET /api/v1/sales/orders?customer_id={customerId}&status[]=draft&status[]=confirmed&status[]=processing

Orders awaiting shipment:

GET /api/v1/sales/orders?status=processing&sort=-created_at

Next steps

• Invoice Generation
• Payment Processing
• Order-to-Cash Workflow