Orders API

Complete order lifecycle management from creation to fulfillment

Overview

The Orders API provides comprehensive order management capabilities including order placement, status tracking, customer order history, and complete lifecycle management from creation to fulfillment.

Order Statuses

pending
processing
confirmed
in_progress
completed
cancelled
refunded
on_hold

Features

Customer order tracking
Status management
Order cancellation
Custom metadata
Flexible filtering

Analytics

Order statistics
Revenue tracking
Status breakdown
Customer insights

Note: Customer data is stored on an external platform (userhub). Orders reference customers via customer_id field only.

Method	Endpoint	Description	Requirements
Order Management
POST	/api/orders/place	Place a new order	`customer_id (required) – Customer ID from userhub` `items (required) – Array of order items with product_id, product_name, quantity, price` `billing (required) – Billing information object with first_name, last_name, email` `total (optional) – Total amount (auto-calculated if not provided)` `total_tax (optional) – Tax amount` `status (optional) – Initial status (default: pending)` `notes (optional) – Order notes` `metadata (optional) – Custom metadata object`
GET	/api/orders/{id}	Retrieve order details by ID	`id (required) – Order database ID`
POST	/api/orders/{id}/action	Perform action on order (update status, cancel, complete, update metadata)	`id (required) – Order database ID` `action (required) – Action name: update_status, cancel, complete, update_metadata` `+ Additional parameters based on action`
Statistics & Reference
GET	/api/orders/stats	Get order statistics and metrics	`customer_id (optional) – Filter by customer` `date_from (optional) – Start date (YYYY-MM-DD)` `date_to (optional) – End date (YYYY-MM-DD)`
GET	/api/orders/meta/statuses	Get list of available order statuses
Order Queries
GET	/api/orders/list	List orders with filtering and pagination	`customer_id (optional) – Filter by customer ID` `status (optional) – Filter by order status` `active_only (optional) – Show only active orders (excludes completed/cancelled/refunded)` `search (optional) – Search by order_id, customer_id, or billing info` `date_from (optional) – Start date filter (YYYY-MM-DD)` `date_to (optional) – End date filter (YYYY-MM-DD)` `order_by (optional) – Sort field (default: created_at)` `order_direction (optional) – Sort direction (asc/desc, default: desc)` `per_page (optional) – Results per page (default: 15)` `customer_id (optional) – Filter by customer (use instead of /customer/{id} endpoint)` `user_id (optional) – Filter by user ID from Userhub`

Request Examples

Place New Order

POST /api/orders/place

{ "customer_id": "CUST-12345", "items": [ { "product_id": 1, "product_name": "Premium Cleaning Service", "quantity": 1, "price": 150.00, "metadata": { "filter_options": [1, 2, 3] } }, { "product_id": 2, "product_name": "Window Cleaning", "quantity": 2, "price": 75.00 } ], "billing": { "first_name": "John", "last_name": "Doe", "email": "john.doe@example.com", "phone": "+31612345678", "address": "123 Main Street", "city": "Amsterdam", "postal_code": "1012AB", "country": "NL" }, "notes": "Please call before arrival", "metadata": { "source": "webform", "campaign_id": "SUMMER2025" } }

Place Order Response

{ "success": true, "message": "Order placed successfully", "data": { "id": 3, "order_id": 421409, "customer_id": "CUST-12345", "total": "300.00", "total_tax": "0.00", "status": "pending", "currency_symbol": "€", "items": [...], "billing": {...}, "notes": "Please call before arrival", "created_at": "2025-11-06T15:00:00.000000Z", "updated_at": "2025-11-06T15:00:00.000000Z" } }

Update Order Status (Unified Action Endpoint)

POST /api/orders/3/action

{ "action": "update_status", "status": "in_progress", "notes": "Work has started" }

Complete Order

POST /api/orders/3/action

{ "action": "complete", "notes": "Order delivered successfully" }

List Orders Response

GET /api/orders/list?customer_id=CUST-12345&status=completed

{ "success": true, "data": [ { "id": 3, "order_id": 421409, "customer_id": "CUST-12345", "total": "300.00", "status": "completed", "created_at": "2025-11-06T15:00:00.000000Z" } ], "pagination": { "current_page": 1, "per_page": 15, "total": 1, "last_page": 1 } }

Order Statistics Response

GET /api/orders/stats/overview?customer_id=CUST-12345

{ "success": true, "data": { "total_orders": 4, "total_revenue": 2450.00, "pending_orders": 1, "processing_orders": 1, "completed_orders": 1, "cancelled_orders": 1, "active_orders": 2 } }

Available Statuses Response

GET /api/orders/statuses/available

{ "success": true, "data": [ "pending", "processing", "confirmed", "in_progress", "completed", "cancelled", "refunded", "on_hold" ] }