Orders API

The Orders module covers the full sales order lifecycle from quotation through delivery and invoicing. Orders are linked to contacts, include line items, and drive automated license issuance and invoice generation.

---

Endpoints

Method	Path	Description
GET	/api/orders	List orders (paginated)
POST	/api/orders	Create an order
GET	/api/orders/:id	Get an order
PATCH	/api/orders/:id	Update an order
DELETE	/api/orders/:id	Delete a draft order
POST	/api/orders/:id/confirm	Confirm a draft order
POST	/api/orders/:id/cancel	Cancel an order
POST	/api/orders/:id/invoice	Create invoice from order
GET	/api/orders/:id/invoices	List invoices for an order

---

Order Status Workflow

draft → confirmed → in_progress → delivered → done
                ↘              ↘
               cancelled      cancelled

Status	Description
draft	Quotation in progress
confirmed	Customer confirmed; licenses issued for digital products
in_progress	Work or shipment in progress
delivered	Delivery complete
done	Order fully closed and paid
cancelled	Order voided

---

List Orders

GET /api/orders?page=1&limit=20&status=confirmed&contactId=018e...&sortBy=createdAt&sortOrder=desc

Query Parameters

Parameter	Type	Description
page	number	Page number
limit	number	Items per page (max: 100)
status	string	Filter by status
contactId	string	Filter by contact UUID
from	ISO 8601	Created after date
to	ISO 8601	Created before date
sortBy	string	total, status, createdAt, updatedAt

Response

{
  "data": [
    {
      "id": "018eaaaa-abcd-7000-8000-000000000001",
      "reference": "SO/2026/0042",
      "status": "confirmed",
      "contact": {
        "id": "018e1234-abcd-7000-8000-000000000001",
        "name": "Acme Corporation",
        "email": "[email protected]"
      },
      "lineItems": [
        {
          "productId": "018e5678-abcd-7000-8000-000000000001",
          "productName": "ECOSIRE Shopify Connector",
          "quantity": 1,
          "unitPrice": 49900,
          "total": 49900
        }
      ],
      "subtotal": 49900,
      "tax": 0,
      "total": 49900,
      "currency": "usd",
      "createdAt": "2026-03-15T10:00:00Z",
      "updatedAt": "2026-03-15T10:05:00Z"
    }
  ],
  "meta": { "total": 128, "page": 1, "limit": 20, "totalPages": 7 }
}

---

Create an Order

POST /api/orders
Content-Type: application/json
Authorization: Bearer eco_live_...

Request Body

{
  "contactId": "018e1234-abcd-7000-8000-000000000001",
  "lineItems": [
    {
      "productId": "018e5678-abcd-7000-8000-000000000001",
      "quantity": 1,
      "unitPrice": 49900
    }
  ],
  "currency": "usd",
  "notes": "Priority onboarding requested."
}

Required fields: contactId, lineItems (at least one item with productId, quantity, unitPrice)

Response: 201 Created with the order in draft status.

---

Confirm an Order

Transitions the order from draft to confirmed. For digital products, licenses are automatically issued.

POST /api/orders/018eaaaa-abcd-7000-8000-000000000001/confirm

Response:

{
  "id": "018eaaaa-abcd-7000-8000-000000000001",
  "status": "confirmed",
  "licenses": [
    {
      "licenseKey": "SHOP-XXXX-XXXX-XXXX-XXXX",
      "productId": "018e5678-abcd-7000-8000-000000000001",
      "activationsLimit": 3,
      "expiresAt": "2027-03-15T10:00:00Z"
    }
  ]
}

---

Cancel an Order

POST /api/orders/018eaaaa-abcd-7000-8000-000000000001/cancel
Content-Type: application/json

{ "reason": "Customer requested cancellation" }

Cancelling a confirmed order suspends associated licenses. Returns 200 OK.

---

Create Invoice from Order

POST /api/orders/018eaaaa-abcd-7000-8000-000000000001/invoice
Content-Type: application/json

{
  "dueDate": "2026-04-15T00:00:00Z",
  "notes": "Payment due within 30 days."
}

Response: 201 Created with the new invoice object. See Invoices API for the full schema.

---

Status Codes

Code	Scenario
200	Get, confirm, or cancel succeeded
201	Order or invoice created
204	Draft order deleted
400	Attempt to delete a non-draft order
404	Order not found
409	Order already in target state (e.g., confirming a confirmed order)
422	Validation failure on line items