E-commerce orders — list, detail, history, create, update, and printable invoice projection.
List orders
Paginated org orders with full inline relations — items, payments, origin address, contact, product types. Mirrors chatmo-dashboard /api/ecommerce/orders field-for-field.
Decimal fields (unit_price, total, discount, ...) are JSON strings to preserve precision.
Performance: 7 queries flat — list + count + items + payments + origin addresses + contacts + product types. All batched. No N+1.
query Parameters
product_idEXISTS subquery on order_items.
customer_idchannelpayment_statusorder_statusdate_fromYYYY-MM-DD or RFC 3339. Inclusive lower bound on created_at.
date_toYYYY-MM-DD or RFC 3339. Inclusive upper bound on created_at. Bare dates are auto-bumped to end-of-day.
searchILIKE on order_number, customer_name, customer_phone (multi-field).
sort_bysort_orderpage1-indexed page number. Capped at 500 to bound deep-scan cost.
limitRows per page. Capped at 100.
List orders › Responses
Orders page.
successCreate an order
Creates a new order. order_number is auto-allocated (ORD-000123 pattern). Subtotal is computed from items × snapshot product prices; total = subtotal − discount + shipping_cost.
Customer resolution: pass customer_id to attach an existing Contact (server snapshots name / email / phone). Otherwise supply raw customer_name + customer_phone — these create no contact row, they live on the order only.
Payment flow: when payment_method_id is given, the server reads ecommerce_payment_methods and inserts an initial ecommerce_order_payments row with status=PENDING. If the method is AUTOMATIC + XENDIT, the server calls Xendit's POST /v2/invoices and patches the payment row with the invoice URL, Xendit invoice id, and expiry (24h TTL). Xendit failure does NOT roll back the order — the order is saved first; mobile can retry the payment-link generation separately.
Create an order › Request Body
customer_idExisting contact id. When set, server snapshots name / email / phone — raw fields override per-order.
customer_nameRequired when customer_id is not provided.
customer_emailcustomer_phoneRequired when customer_id is not provided.
customer_channelcourier_codecourier_namecourier_serviceshipping_costorigin_address_idpayment_method_idDrives the payment row + Xendit invoice creation when the method is AUTOMATIC+XENDIT.
notesdiscount_typediscount_valueCreate an order › Responses
Order created.
successUpdate an order
Update editable fields on an existing order. Empty body returns 400.
Status side-effects (order_status): SHIPPING → stamps shipped_at; COMPLETED → delivered_at; CANCELLED → cancelled_at + cancelled_by.
History side-effect: status changes auto-write a STATUS_CHANGED row to ecommerce_order_history with structured metadata. Tracking-number changes write a TRACKING_UPDATED row with before/after values. Internal notes do NOT auto-history (internal only). All writes happen inside one transaction.
path Parameters
order_idUUID of the order.
Update an order › Request Body
order_statusSide-effects: SHIPPING → shipped_at, COMPLETED → delivered_at, CANCELLED → cancelled_at + cancelled_by.
tracking_numberinternal_notesUpdate an order › Responses
Updated order.
successOrder activity history
Paginated history rows for the order. Used by the mobile order-detail screen's Activity tab.
created_by_user is null for system-generated rows (e.g. Xendit webhook updates with no human actor).
path Parameters
order_idUUID of the order.
query Parameters
page1-indexed page number. Capped at 500 to bound deep-scan cost.
limitOrder activity history › Responses
History page.
successPrintable invoice projection
Slim printable-invoice projection of an order — only the fields a customer-facing invoice / PDF needs. Drops internal_notes, metadata, and weight from the full order shape.
When the organization has not yet configured ecommerce_invoice_templates, template is null and template_configured = false — render a Set up invoice branding CTA.
courier, origin_address, and payment are nullable — omitted when the underlying fields are empty. payment is the latest row (newest created_at) attached to the order.
Performance: 3-5 flat queries per request. No N+1.
path Parameters
order_idUUID of the order.
Printable invoice projection › Responses
Invoice projection.
success