Orders

The Orders resource lives at /api/v1/orders and requires the orders permission. Responses use the standard envelope.

Endpoints

Method	Path	Purpose
GET	/api/v1/orders	List orders (paginated).
GET	/api/v1/orders/:id	Read one order.
POST	/api/v1/orders	Create a manual order.
PUT	/api/v1/orders/:id/status	Advance the order status.
POST	/api/v1/orders/:id/cancel	Cancel an order.
POST	/api/v1/orders/track	Look up an order by tracking details.

List response

{
  "success": true,
  "message": "Orders fetched successfully",
  "data": {
    "orders": [ /* order objects */ ],
    "pagination": { "page": 1, "limit": 20, "total": 340, "pages": 17 }
  }
}

The order object (key fields)

Field	Type	Notes
id	string (UUID)
orderNumber	string | null	Sequential, per-store, human-facing.
customerId	string
source	enum	web, mobile_app, api, pos, manual.
status	enum	See lifecycle below.
paymentStatus	enum	pending, authorized, paid, failed, partially_refunded, refunded, cancelled.
paymentMethod	enum	cash, card, wallet, bank_transfer, installment.
subtotalAmount	decimal	Items before adjustments.
discountAmount	decimal
taxAmount	decimal
shippingCost	decimal
codFee	decimal	Cash-on-delivery surcharge, if any.
finalAmount	decimal	What the customer pays.
refundedAmount	decimal	Cumulative refunded.
currency	string	ISO code the order settled in.
couponCode	string | null
shippingAddress	object
requiresShipping	boolean	Digital-only orders are false and skip shipping states.
items	array	Line items (via include).
createdAt / updatedAt	datetime

Order status lifecycle

status is one of: pending_payment, pending, confirmed, processing, shipped, delivered, on_hold, returned, refunded, partially_refunded, cancelled, payment_failed.

A non-shipping order (all items digital) skips processing/shipped and moves straight toward delivered.