# Orders Module

Provides order lifecycle management with customer info, line items, payments, and inventory adjustments.

## Endpoints
- `POST /orders`
  - Creates an order with customer name/phone (required), optional email/address/notes, items, and optional payment.
  - Decrements product (and variant, when provided) stock atomically; fails if insufficient stock.
- `GET /orders`
  - Lists orders with pagination and optional `status` filter.
- `GET /orders/:id`
  - Retrieves a single order with items and payments.
- `PATCH /orders/:id/status`
  - Updates order status; switching to `returned` restocks items, leaving `returned` consumes stock again.

## Data Notes
- Supported statuses: `pending`, `paid`, `shipped`, `delivered`, `returned`, `cancelled`.
- Payment records are optional; currency must match the order currency.
- Item pricing snapshots use the product’s `price` at order time.
- `customerEmail` is optional and can be reused across multiple orders.