# Frontend API requests and responses

This guide documents request payloads and representative success response
shapes for the frontend-facing API. Examples use the standard JSON envelope
unless stated otherwise. Error responses use `Response::simple()` as described
in [Common response shapes](#common-response-shapes).

## Request conventions

- Endpoint URLs use the deployment's private API route, e.g. `/app/v1/{endpoint}`.
- Values such as IDs, slugs and page numbers go in the URL path after the endpoint, in the
  order each endpoint lists, e.g. `/app/v1/get-admin-logs/{adminId}/{page}`. They are not
  JSON fields or query-string parameters. Each path value may contain only letters, digits,
  `-` and `_`. To give a later value without an earlier optional one, send the earlier one
  explicitly, e.g. page `1`.
- Send JSON examples as `Content-Type: application/json`. File-upload routes use
  `multipart/form-data`; attach the listed file fields separately.
- Auth requirements follow the route middleware. “No body” means the handler
  does not read a request body.
- Every successful signed-in response (`statusCode` 100) includes a top-level
  `authentication` object, `{ refreshToken, tokenExpiry }`. Replace the stored
  `jwToken` with `refreshToken`. The session ends after `JWT_VALIDITY` hours with
  no successful request. Error responses never include it. There's no `adminSecret`
  in it: admins keep sending the one from sign-in until they sign in again.

## Request signing

Every API request sends three headers. Otherwise it's refused with 401
"Invalid request signature." In development only, a request with none of the three is let
through, for Postman and curl.

| Header | Value |
| --- | --- |
| `Request-Time` | `Date.now()` as a string (unix milliseconds). Must be within 3 minutes of server time; otherwise 401 "Request expired…" |
| `Platform-Signature` | HMAC-SHA256 hex of `PLATFORM_DOMAIN`, keyed with `DOMAIN_HMAC_SECRET` + the UTC hour of `Request-Time` as `YYYYMMDDHH` |
| `Request-Signature` | HMAC-SHA256 hex of `METHOD + pathWithQuery + Request-Time + rawBody`, keyed with `SIGNATURE_HMAC_SECRET` + the same hour as `YYYY,MM,DD,HH` |

```js
const time = Date.now().toString();
const iso = new Date(Number(time)).toISOString();               // 2026-11-17T10:04:12.345Z
const [y, m, d, h] = [iso.slice(0, 4), iso.slice(5, 7), iso.slice(8, 10), iso.slice(11, 13)];
headers["Request-Time"] = time;
headers["Platform-Signature"] = hmacSha256Hex(PLATFORM_DOMAIN, DOMAIN_SECRET + y + m + d + h);
headers["Request-Signature"] = hmacSha256Hex(
    method.toUpperCase() + pathWithQuery + time + rawBody,       // rawBody is "" for GET
    SIGNING_SECRET + [y, m, d, h].join(","),
);
```

- `pathWithQuery` is exactly the path (and query string, if any) sent, e.g.
  `/app/v1/get-my-reviews/2`.
- `rawBody` is the exact JSON string sent. Sign it, then send that same string. Re-serialising
  after signing breaks the signature. For `multipart/form-data` uploads PHP doesn't
  expose the raw body, so sign with `rawBody = ""`.
- Admin routes may also be limited to listed IPs (403 "Access denied.").

## Endpoint request reference

| Endpoint                            | Request body / query parameters                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| ----------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `file-serve`                        | **Currently disabled** (route commented out; returns 404). When enabled: no body, query `path=uploads/example.jpg`; private auth required.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `create-account`                    | JSON: [account signup](#account-signup).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `resend-auth-otp`                   | JSON: [resend OTP](#resend-otp); use `action: "email_verify"`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `verify-auth-otp`                   | JSON: [verify OTP](#verify-otp); use `action: "email_verify"`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `user-signin`                       | JSON: [sign-in](#sign-in). 409 if the email hasn't been verified: send the customer to the code screen (`verify-auth-otp`, and `resend-auth-otp` for a new code), then sign in again.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `forgot-password`                   | JSON: [forgot password](#forgot-password).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `resend-password-otp`               | JSON: [resend OTP](#resend-otp); use `action: "password_reset"`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `verify-password-otp`               | JSON: [verify OTP](#verify-otp); use `action: "password_reset"`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `reset-password`                    | JSON: [reset password](#reset-password). Call within 10 minutes of verifying the code; each code works once.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `change-password`                   | JSON: [change password](#change-password); private auth required.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `admin-get-customers`               | `GET`, no body. Optional path `admin-get-customers/{page}` (defaults to 1); paginated customer list; admin auth required.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `get-customer-analytics`            | `GET`, no body. Path `get-customer-analytics/{customerId}` (the `id` from `admin-get-customers`); one customer's profile, order summary, recent orders and addresses ([customer details](#customer-details)); admin auth required. 404 for an unknown or deleted customer.                                                                                                                                                                                                                                                                                                                                                       |
| `update-user-profile`               | JSON: [update profile](#update-profile); private auth required.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `update-user-email`                 | `PATCH`/`PUT` JSON: `{ "email": "amina@example.com" }`; private auth required. Starts an email change: a verification code is sent to the **new** address, and the account email does not change until `confirm-user-email` succeeds. 422 if it is already your email; 409 if another customer uses it.                                                                                                                                                                                                                                                                                                                          |
| `confirm-user-email`                | `PATCH`/`PUT` JSON: `{ "email": "<new address>", "action": "email_change", "otpCode": "123456" }`; private auth required. Applies the pending email change. 422 when no change is pending for that address; 400 for a wrong or expired code; 429 after too many attempts; 409 if the address was taken meanwhile.                                                                                                                                                                                                                                                                                                                |
| `resend-confirmation-otp`           | `POST`, no body; private auth required. Sends a new code to the pending (new) address. 422 when no change is pending; 429 after 3 codes in 5 minutes.                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `create-admin`                      | JSON: [create admin](#create-admin); admin auth required.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `get-all-admins`                    | No body. Optional path `get-all-admins/{page}` (defaults to 1); paginated; superadmin only.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `get-admin-logs`                    | `GET`, no body. Path `get-admin-logs/{adminId}/{page}` (`{page}` optional); activity log for one admin; admin auth required.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `get-all-activity-logs`             | `GET`, no body. Optional path `get-all-activity-logs/{page}`; activity log for all admins; super admin only.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `forgot-admin-password`             | JSON: [forgot password](#forgot-password). Then verify the code and call `reset-admin-password` within 10 minutes.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `resend-admin-password-otp`         | JSON: [resend OTP](#resend-otp); use `action: "password_reset"`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `verify-admin-password-otp`         | JSON: [verify OTP](#verify-otp); use `action: "password_reset"`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `reset-admin-password`              | JSON: [reset password](#reset-password).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `admin-signin`                      | JSON: [sign-in](#sign-in). Checks the password and emails a 6-digit sign-in code; returns `{ "email" }`, no token. Call it again to get a new code (3 per 5 minutes).                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `verify-admin-signin-otp`           | JSON: [verify OTP](#verify-otp); use `action: "two_factor"`. Returns the admin profile with `jwToken`, `tokenExpiry` and `adminSecret`. The code expires after 5 minutes and allows 3 attempts.                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `create-category`                   | Multipart: [category fields](#category-fields); send `categoryIcon` as text and attach required `categoryImage` and `categoryBanner` files.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `update-category`                   | POST multipart: [category fields](#category-fields); include `id` (or pass it in the path: `update-category/{categoryId}`); send `categoryIcon` as text; replacement `categoryImage` and `categoryBanner` files are optional. PATCH is accepted only with a JSON body, because PHP does not parse multipart PATCH requests, so image replacement requires POST.                                                                                                                                                                                                                                                                  |
| `delete-category`                   | `DELETE`, no body. Path `delete-category/{categoryId}`. Returns 409 while the category still has products, including archived or soft-deleted ones.                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `get-category`                      | No body. Path `get-category/{categoryId}`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `get-all-categories`                | No body.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `get-attributes`                    | No body. Path `get-attributes/{categoryId}`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `get-all-attributes`                | `GET`, no body. Returns every active category with its active attributes: `[{ "id", "name", "slug", "attributes": [{ "id", "name" }] }]`; categories without attributes have `"attributes": []`.                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `create-product`                    | `POST` multipart: [product fields](#product-fields); at least one image required via `productImages[]`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `update-product`                    | `POST` multipart: full replacement using [product fields](#product-fields); path `update-product/{productId}`; `productImages[]` optional.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `patch-product`                     | `PATCH`/`PUT` JSON: [product patch](#product-patch); path `patch-product/{productId}`; admin auth required.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `delete-product`                    | `DELETE`, no body. Path `delete-product/{productId}`; admin auth required. Products with no orders are permanently removed 90 days later.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `get-product`                       | No body. Path `get-product/{productId}`; returns an active product.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `get-product-by-slug`               | `GET`, no body. Path `get-product-by-slug/{slug}`; returns one active product (public resource).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `get-category-products`             | `GET`, no body. Path `get-category-products/{categoryId}/{page}` (`{page}` optional); paginated active products in the category. Public resource, or the admin resource for a signed-in admin.                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `search-products`                   | `GET`, no body. `search-products/{term}/{page}`; `{term}` may only hold letters, digits and `-`, so remove accents and replace every other character with `-` ("+adida sneakr-" becomes `adida-sneakr`), up to 100 characters; the page defaults to 1. Paginated active products, public resource. Each word must match the name, brand, description, category or a variant colour or size; if no product matches every word, products matching any word are returned, most words first, with `meta.exactMatch: false`. Words under 2 characters are ignored; 422 when none is left.                                             |
| `admin-get-product`                 | No body. Path `admin-get-product/{productId}`; admin auth required.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `get-all-products`                  | No body. Optional path `get-all-products/{page}` (defaults to 1); paginated; admin auth required.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `create-limited-time-offer`         | JSON: [limited-time offer](#limited-time-offer).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `update-limited-time-offer`         | Same JSON; path `update-limited-time-offer/{offerId}`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `delete-limited-time-offer`         | No body. Path `delete-limited-time-offer/{offerId}`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `get-all-limited-time-offers`       | No body.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `get-active-offers`                 | No body.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `get-active-limited-time-offers`    | `GET`, no body; same handler and response as `get-active-offers`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `get-featured-products`             | No body.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `save-store-settings`               | Multipart: [store settings](#store-settings); `storeLogo` is required when creating and optional when updating; optional `storeSubmarkLogo` is uploaded when provided.                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `send-contact-message`              | `POST` `{ "fullName", "email", "subject", "message" }`, all required; name and subject up to 100 characters, email 150, message 500. Emails the support inbox and copies the store email (Reply-To is the visitor). Returns `data: []`; 422 on validation, 503 if the email could not be sent, 429 after 10 requests a minute per IP (shared with the other auth endpoints).                                                                                                                                                                                                                                                     |
| `get-initial-data`                  | `GET`, no body. Returns `{ settings, policies, categories }`: the same object as `get-store-settings`, active store policies, and page 1 of `get-all-categories`. Call it once on the first visit; `settings` is `null` if the store has none.                                                                                                                                                                                                                                                                                                                                                                                   |
| `get-store-settings`                | No body.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `get-shipping-settings`             | No body.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `get-shipping-locations`            | `GET`, no body. Active delivery states with their active zones, for checkout; private auth required.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `save-shipping-settings`            | JSON: [shipping settings](#shipping-settings).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `update-shipping-settings`          | JSON: [shipping settings](#shipping-settings); include `id`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `delete-shipping-settings`          | No body. Path `delete-shipping-settings/{shippingSettingsId}`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `get-regional-shipping-settings`    | No body. Path `get-regional-shipping-settings/{stateId}`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `save-regional-shipping-settings`   | JSON: [regional shipping settings](#regional-shipping-settings).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `update-regional-shipping-settings` | Same JSON; include `id`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `delete-regional-shipping-settings` | No body. Path `delete-regional-shipping-settings/{regionalShippingId}`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `get-store-policy`                  | No body. Path `get-store-policy/{policySlug}`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `get-all-store-policies`            | No body.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `create-store-policy`               | JSON: [create policy](#store-policy).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `update-store-policy`               | JSON: [update policy](#store-policy).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `save-cart`                         | JSON: [cart item](#cart). Guests: send no `sessionToken` on the first add; the response's `data.sessionToken` is the guest's token. Store it and send it on every later cart call. An unknown token gets a new one, so always keep the latest. `null` for signed-in customers, who send `Authorization: Customer {jwt}`.                                                                                                                                                                                                                                                                                                         |
| `add-cart-items`                    | `POST` JSON: [multiple cart items](#multiple-cart-items). At most 50 items, each variant once per request (422 otherwise). All or nothing: if any item fails, none are saved. Guests: send no `sessionToken` on the first add; the response's `data.sessionToken` is the guest's token. Store it and send it on every later cart call. An unknown token gets a new one, so always keep the latest. `null` for signed-in customers, who send `Authorization: Customer {jwt}`.                                                                                                                                                     |
| `get-cart-items`                    | `GET`, no body. Guests: `get-cart-items/{sessionToken}`. Signed-in customers: `get-cart-items` with no parameter (the customer comes from authentication). 422 when neither is available.                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `update-cart-item`                  | JSON: [cart item](#cart); path `update-cart-item/{cartItemId}`. Guests must send their `sessionToken`. 404 when the item is not in the caller's cart; 422 when the quantity exceeds stock.                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `delete-cart-item`                  | `DELETE`, no body. Guests: `delete-cart-item/{cartItemId}/{sessionToken}`; signed-in customers: `delete-cart-item/{cartItemId}`. 404 when the item is not in the caller's cart.                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `admin-delete-cart`                 | `DELETE`, no body. Path `admin-delete-cart/{cartId}`. Deletes the cart and all its items; returns `{ "cartId", "itemsDeleted" }`. 404 for an unknown cart; admin auth required.                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `clear-cart`                        | `DELETE`, no body. Guests: `clear-cart/{sessionToken}`; signed-in customers: `clear-cart` with no parameter. 422 when neither is available.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `merge-cart`                        | `POST` JSON: [merge cart](#merge-cart). Requires `Authorization: Customer {jwt}` (401 otherwise). Succeeds with no change when there is nothing to merge; merged quantities are capped at stock.                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `get-all-cart-items`                | No body; admin auth required.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `save-pickup-location`              | JSON: [pickup location](#pickup-location); admin auth required.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `get-pickup-location`               | No body. Path `get-pickup-location/{pickupLocationId}`; returns 404 for an inactive location.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `get-pickup-locations`              | No body. Returns active locations only.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `admin-get-pickup-locations`        | No body. Returns all locations, including inactive ones; admin auth required.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `update-pickup-location`            | JSON: [pickup location](#pickup-location); path `update-pickup-location/{pickupLocationId}`; admin auth required.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `delete-pickup-location`            | No body. Path `delete-pickup-location/{pickupLocationId}`; admin auth required.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `update-status`                     | `PATCH`/`PUT` JSON: [status update](#status-update); admin auth required.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `get-admin-profile`                 | `GET`, no body. Returns the signed-in admin; admin auth required.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `update-admin-profile`              | `PATCH`/`PUT` JSON: [admin profile](#admin-accounts); signed-in admin's own account.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `change-admin-password`             | `PATCH`/`PUT` JSON: [admin password](#admin-accounts); signed-in admin's own account.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `update-admin`                      | `PATCH`/`PUT` JSON: [admin details](#admin-accounts); path `update-admin/{adminId}`; super admin only.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `delete-admin`                      | `DELETE`, no body. Path `delete-admin/{adminId}`; super admin only.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `create-order`                      | POST JSON: [create order](#create-order); customer bearer token required. The router does not enforce HTTP methods.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `update-order`                      | JSON: [update order](#update-order); path `update-order/{orderId}`; admin auth required.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `get-my-orders`                     | `GET`, no body. Optional path `get-my-orders/{page}` (defaults to 1); the signed-in customer's orders, newest first ([order lists](#order-lists-and-details)); private auth required.                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `get-my-order`                      | `GET`, no body. Path `get-my-order/{orderId}` or `get-my-order/{orderNumber}`; one of the signed-in customer's orders with items, each item's review, and delivery details; private auth required. 404 for another customer's order.                                                                                                                                                                                                                                                                                                                                                                                             |
| `confirm-payment`                   | `POST`, no body. Path `confirm-payment/{orderId}` or `confirm-payment/{orderNumber}`; the signed-in customer's own order. Adds up the order's successful payments and settles it: see [confirm payment](#confirm-payment). 404 for another customer's order.                                                                                                                                                                                                                                                                                                                                                                     |
| `admin-get-orders`                  | `GET`, no body. Optional path `admin-get-orders/{page}/{status}`; to filter by status from the first page use `admin-get-orders/1/{status}` (`pending`, `processing`, `shipped`, `delivered`, `cancelled`, `refunded`, `failed`); all orders, newest first; admin auth required. 422 for an unknown status.                                                                                                                                                                                                                                                                                                                      |
| `admin-get-order`                   | `GET`, no body. Path `admin-get-order/{orderId}` or `admin-get-order/{orderNumber}`; the order with profit figures, customer, shipping, delivery timeline, items and payment history ([admin order details](#admin-order-details)); admin auth required. 404 for an unknown order.                                                                                                                                                                                                                                                                                                                                               |
| `generate-payment-account`          | `POST`, no body. Path `generate-payment-account/{orderId}` or `generate-payment-account/{orderNumber}`; admin auth required. Gives a pending, processing or shipped order that still owes money an account to pay into and returns `accountNumber`, `accountName`, `bankName`, `amount`, `amountDueOnDelivery`, `reference`, `expiresAt` and `isNew`. `amount` is the delivery fee for an `unpaid` cash-on-delivery order with a fee, the balance for a `delivery_paid` order, and the order total otherwise. If the order already has a live account for that amount, it is returned with `isNew: false`. 422 if the order is delivered, closed or fully paid. |
| `get-all-payments`                  | `GET`, no body. Optional path `get-all-payments/{page}/{status}`; to filter by status from the first page use `get-all-payments/1/{status}` (`pending`, `successful`, `failed`, `reversed`); all payments, newest first, each with `id`, `orderId`, `orderNumber`, `customerName`, `amount`, `currency`, `provider`, `providerReference`, `bankReference`, `paymentBankName`, `accountCredited`, `channel`, `status`, `paidAt` (e.g. `May 5, 2025 10:23:29 AM`); admin auth required. 422 for an unknown status.                                                                                                                 |
| `get-system-analytics`              | `GET`, no body; store totals, monthly growth, sales trend, recent orders, best sellers and low stock ([admin dashboard](#admin-dashboard)); admin auth required.                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `create-review`                     | `POST` JSON: `{ "orderItemId": 10, "rating": 4, "review": "Lovely watch, quick delivery." }`; private auth required. `orderItemId` is the item's `id` from `get-my-order`. `rating` is 1–5 and `review` at most 1000 characters. 422 until the order is delivered; 404 for another customer's item; 400 if the item already has a review.                                                                                                                                                                                                                                                                                        |
| `get-reviews`                       | `GET`, no body. Optional path `get-reviews/{page}`; visible reviews only ([reviews](#reviews)); no auth.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `get-my-reviews`                    | `GET`, no body. Optional path `get-my-reviews/{page}` (defaults to 1); the signed-in customer's reviews, hidden ones included ([reviews](#reviews)); private auth required. |
| `get-product-reviews`               | `GET`, no body. Path `get-product-reviews/{productId}/{page}` (`{page}` optional); visible reviews of one active product, 10 per page ([reviews](#reviews)); no auth. 404 if the product isn't active.                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `admin-get-reviews`                 | `GET`, no body. Optional path `admin-get-reviews/{page}`; all reviews, including hidden ones; admin auth required.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `admin-update-review-status`        | `PATCH`/`PUT` JSON: `{ "status": 1 }` to show or `{ "status": 0 }` to hide; path `admin-update-review-status/{reviewId}`; admin auth required.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `admin-delete-review`               | `DELETE`, no body. Path `admin-delete-review/{reviewId}`; permanently deletes the review (use status `0` to hide it instead); admin auth required.                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `admin-dashboard`                   | No body defined; no dashboard handler is currently dispatched.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |

### Account signup

Used by `create-account`:

```json
{
    "firstName": "Amina",
    "lastName": "Okafor",
    "email": "amina@example.com",
    "phone": "+2348012345678",
    "gender": "female",
    "password": "ExamplePass123!",
    "confirmPassword": "ExamplePass123!"
}
```

### Resend OTP

`action` is required in the body. Use the action listed for the endpoint above.

```json
{ "email": "amina@example.com", "action": "email_verify" }
```

### Verify OTP

```json
{
    "email": "amina@example.com",
    "action": "email_verify",
    "otpCode": "123456"
}
```

### Sign-in

Used by `admin-signin` and `user-signin`.

```json
{ "email": "amina@example.com", "password": "ExamplePass123!" }
```

### Forgot password

```json
{ "email": "amina@example.com" }
```

### Reset password

Used by `reset-password` and `reset-admin-password`:

```json
{
    "email": "amina@example.com",
    "otpCode": "123456",
    "newPassword": "NewExamplePass123!",
    "confirmPassword": "NewExamplePass123!"
}
```

### Change password

```json
{
    "oldPassword": "ExamplePass123!",
    "newPassword": "NewExamplePass123!",
    "confirmPassword": "NewExamplePass123!"
}
```

### Update profile

```json
{
    "firstName": "Amina",
    "lastName": "Okafor",
    "phone": "+2348012345678",
    "gender": "female",
    "email": "amina@example.com"
}
```

### Create admin

```json
{
    "firstName": "Chidi",
    "lastName": "Nwosu",
    "email": "chidi@example.com",
    "role": "admin",
    "password": "ExamplePass123!",
    "confirmPassword": "ExamplePass123!"
}
```

### Category fields

Text fields for `create-category`:

```json
{
    "name": "Accessories",
    "slug": "accessories",
    "description": "Accessories",
    "categoryIcon": "fa-kola",
    "bannerTitle": "New season accessories",
    "extraQuantityThreshold": 10,
    "additionalShippingFee": 500,
    "attributes": ["Size", "Color"]
}
```

For multipart requests, send `categoryIcon` as a text field. Attach
`categoryImage` (square JPG/PNG, 500×500 minimum) and `categoryBanner` (JPG/PNG).
Both files are required on create. For
`update-category`, include `id` in the multipart body; replacement image files
are optional. The update handler does not accept the `attributes` list.

`bannerTitle` is optional text (max 150 characters) shown with the category
banner. Updates replace it with the value sent; leaving it out or sending it
empty clears it.

The optional `extraQuantityThreshold` and `additionalShippingFee` fields must
be supplied together. Send both as `null` or empty values to clear them; when
updating, omitted values are retained. For courier orders, the additional
shipping fee is charged once for each complete quantity threshold within each
category. For example, a threshold of 30 and a fee of 500 adds 500 for 30-59
items, 1,000 for 60-89, and 1,500 for 90 items. This surcharge is added to the
configured courier delivery fee and does not apply to pickup orders.

### Product fields

`create-product` and `update-product` accept this structured payload; use the
camelCase field names shown here. For uploads, send these fields as multipart
form fields and files as `productImages[]`:

```json
{
    "product": {
        "categoryId": 1,
        "name": "Cotton Shirt",
        "slug": "cotton-shirt",
        "sku": "SHIRT-001",
        "shortDescription": "Soft cotton shirt",
        "description": "A comfortable everyday shirt.",
        "costPrice": 5000,
        "basePrice": 8500,
        "oldPrice": 9000,
        "brand": "Example",
        "ageRange": "18-25",
        "gender": "female",
        "weightGrams": 250,
        "isFeatured": false,
        "customBadge": "Limited Edition",
        "status": "active"
    },
    "discountTier": [{ "minQuantity": 3, "discountPerItem": 250 }],
    "variants": [
        {
            "colorName": "Blue",
            "colorHex": "#0000FF",
            "size": "M",
            "sku": "SHIRT-001-BLU",
            "priceOverride": null,
            "costPrice": null,
            "stockQuantity": 20,
            "lowStockThreshold": 5,
            "status": "active"
        }
    ],
    "features": [{ "featureName": "Material", "featureValue": "Cotton" }],
    "attributes": [
        { "id": 2, "value": "Large" },
        { "id": 3, "value": "Blue" }
    ],
    "specifications": [
        {
            "specificationName": "Fabric weight",
            "specificationValue": "180 gsm"
        }
    ],
    "whatsinbox": [{ "itemName": "Shirt", "itemQuantity": "1" }],
    "images": []
}
```

Both endpoints require at least one entry in each of `variants`, `attributes`,
`specifications`, and `whatsinbox`; an empty list returns 422. Each category
attribute ID must be active and belong to the product's selected category.

Send these requests as `POST` with `multipart/form-data`. Multipart `PUT` or
`PATCH` bodies are only parsed on PHP 8.4+, and on older versions the fields
and files arrive empty. To change only a few fields without uploading images,
use [product patch](#product-patch).

**Images.** Attach up to five files as `productImages[]` (JPG or PNG, max 2 MB,
at least 600×600). `images` holds optional metadata matched to files by index:
`altText`, `sortOrder` (defaults to the index), and `variantSku` (must be the
SKU of a variant in the same request). `create-product` requires at least one
image.

**Variants and sizes.** Each variant is one colour and size, with its own `sku`,
`stockQuantity`, and optional `priceOverride` and `costPrice` (the variant's unit
cost; leave it out or send `null` to use the product's `costPrice`, which is what
order profit uses then). `colorName`, `colorHex` (`#RRGGBB`)
and `sku` are required. `stockQuantity` is required and must be at least 1 for a
new variant (no `id`); an existing variant can be set to 0. `size` is optional: leave it out
(or send `""`/`null`) for products without sizes. It is any text up to 30
characters, such as `M`, `42` or `100ML`, saved as sent. Each of these returns 422:

- the same colour and size twice ("Variants 2 and 3 are both Black / 30.")
- the same `sku` twice
- one colour with two different `colorHex` values
- some variants with a size and some without

Colours, sizes and SKUs are compared ignoring case. Link an image to any one variant of
a colour; responses give each image its `colorName`, so it can be shown for every
size of that colour.

**`update-product` replaces the whole product.** Send the complete structure,
not just what changed:

- `product.status`: omit it (or send it empty) to keep the current status; on
  `create-product` it defaults to `draft`.
- `variants`: an entry with `id` updates that variant, and one without `id`
  creates a new variant. Existing variants left out of the list are set to
  inactive, not deleted.
- `features`, `attributes`, `specifications`, and `whatsinbox` are deleted and
  replaced with the submitted lists.
- Images:
    - No `images` and no files: images stay exactly as they are. Use this to update
      product or variant details only.
    - Otherwise `images` is the product's full image list (at most 5), in order:
        - an entry with `imageUrl` (as `get-product` returns it) keeps that image;
        - an entry without `imageUrl` is a new image and takes the next file in
          `productImages[]`, in the order sent.
      The number of entries without `imageUrl` must equal the number of files.
    - Existing images not listed are removed. To replace one, drop its `imageUrl` from
      the entry and send a file. A new variant's image works the same way, with
      `variantSku` set to the new variant's SKU.
    - Files only (no `images`): each file becomes an image, replacing all existing ones.
    - Files need `multipart/form-data`. In a JSON body they arrive as empty objects
      (`{}`) and are ignored.

    Keep three images and add one for a new Gold variant (multipart):

    ```
    images[0] = { "imageUrl": "https://cdn.elegance.ng/media/…main.jpg", "altText": "…", "sortOrder": 0 }
    images[1] = { "imageUrl": "https://cdn.elegance.ng/media/…wine34.jpg", "variantSku": "AMR-PUMP-001-34", "sortOrder": 1 }
    images[2] = { "imageUrl": "https://cdn.elegance.ng/media/…wine30.jpg", "variantSku": "AMR-PUMP-001-30", "sortOrder": 2 }
    images[3] = { "altText": "Amara Block-Heel Pump Gold", "variantSku": "AMR-PUMP-001-GOLD-30", "sortOrder": 3 }
    productImages[] = <Gold file>
    ```

### Product patch

`patch-product/{productId}` (`PATCH` or `PUT`, JSON body) changes
only the fields you send. The body may contain only these top-level keys; any
other key (`features`, `attributes`, `images`, `whatsinbox`, `specifications`)
returns 422:

| Key            | Type   | Purpose                                       |
| -------------- | ------ | --------------------------------------------- |
| `product`      | object | Product fields to change                      |
| `variants`     | array  | Changes to existing variants, matched by `id` |
| `discountTier` | array  | Replaces the whole discount tier list         |

At least one product or variant field is required.

**`product` fields.** Each field can be sent in camelCase or snake_case, but not
both at once.

| camelCase          | snake_case          | Rules                                              |
| ------------------ | ------------------- | -------------------------------------------------- |
| `categoryId`       | `category_id`       | integer ≥ 1; cannot be empty                       |
| `name`             | `name`              | string, max 150; cannot be empty                   |
| `slug`             | `slug`              | valid slug, max 170; cannot be empty               |
| `sku`              | `sku`               | string, max 64; cannot be empty                    |
| `shortDescription` | `short_description` | string, max 255; nullable                          |
| `description`      | `description`       | string; nullable                                   |
| `costPrice`        | `cost_price`        | number ≥ 0; cannot be empty                        |
| `basePrice`        | `base_price`        | number ≥ 0; cannot be empty                        |
| `oldPrice`         | `old_price`         | number ≥ 0; nullable                               |
| `brand`            | `brand`             | string, max 100; nullable                          |
| `weightGrams`      | `weight_grams`      | integer ≥ 0; nullable                              |
| `isFeatured`       | `is_featured`       | boolean; cannot be empty                           |
| `customBadge`      | `custom_badge`      | string, max 30; nullable; `""` or `null` clears it |
| `status`           | `status`            | `draft`, `active`, or `archived`; cannot be empty  |

`ageRange` and `gender` cannot be patched; use `update-product` to change them.

**`variants` entries.** Each entry updates one variant that already belongs to
this product. Variants cannot be added or removed here. Use camelCase; snake_case
names such as `stock_quantity` return 422.

| Field               | Rules                                                                              |
| ------------------- | ---------------------------------------------------------------------------------- |
| `id`                | required; positive integer; must belong to this product; unique within the request |
| `sku`               | string, max 80                                                                     |
| `colorName`         | string, max 50                                                                     |
| `colorHex`          | `#RRGGBB`                                                                          |
| `size`              | string, max 30, e.g. `"M"` or `"42"`; `""` means no size                           |
| `priceOverride`     | number ≥ 0, or `null`                                                              |
| `costPrice`         | number ≥ 0, or `null` to use the product's `costPrice`                             |
| `stockQuantity`     | integer ≥ 0                                                                        |
| `lowStockThreshold` | integer ≥ 0                                                                        |
| `status`            | `active` or `inactive`                                                             |

Each entry needs at least one field besides `id`. A patch that changes `sku`,
`colorName`, `colorHex` or `size` is checked against the product's other variants with
the same rules as creation: each colour and size once, unique SKUs, one `colorHex` per
colour, and sizes on every variant or none (all ignoring case). The check uses the
result of the whole request, so recolouring every variant of a colour, or clearing every
variant's size, works in one request. On failure nothing is saved; messages number the
variants by position (oldest first).

**`discountTier`** follows the same rules as on create: a list of at most 3
tiers, `minQuantity` increasing, and `discountPerItem` a non-negative number.
Sending `[]` clears all tiers.

Change a price and one variant's stock:

```json
{
    "product": { "basePrice": 8000 },
    "variants": [{ "id": 12, "stock_quantity": 18 }]
}
```

Archive a product and deactivate one of its variants:

```json
{
    "product": { "status": "archived" },
    "variants": [{ "id": 12, "status": "inactive" }]
}
```

Replace the discount tiers:

```json
{
    "discountTier": [
        { "minQuantity": 3, "discountPerItem": 250 },
        { "minQuantity": 6, "discountPerItem": 400 }
    ]
}
```

All changes are applied in a single transaction. A failed variant update
returns an error; for example, 422 when a variant doesn't belong to this
product. The response is the updated `ProductModel` (see
[Products](#products)).

### Limited-time offer

```json
{
    "variantId": 12,
    "offerPrice": 7500,
    "startsAt": "2026-10-07 00:00:00",
    "endsAt": "2026-10-14 23:59:59",
    "status": "active"
}
```

Field names are camelCase (`variantId`, `offerPrice`, `startsAt`, `endsAt`);
a missing field returns 422 "<field> is required.". Dates are UTC
`Y-m-d H:i:s` or ISO-8601 with a timezone, with or without milliseconds, so
JavaScript's `toISOString()` output (`2026-10-29T16:56:00.000Z`) works as is.
`endsAt` must be later than `startsAt`; status is `active` or `inactive`.

### Store settings

Text fields for `save-store-settings` (send as multipart form fields when
attaching logo files):

```json
{
    "phoneNumber": "08012345678",
    "whatsappNumber": "08012345678",
    "emailAddress": "store@example.com",
    "storeAddress": "1 Example Road, Lagos",
    "paymentBank": "02",
    "storeName": "Example Store",
    "storeSlogan": "Timeless pieces, everyday elegance",
    "lowStockThreshold": 4,
    "freeDeliveryThreshold": 0,
    "allowPaymentOnDelivery": false,
    "minPodThreshold": 0,
    "maxPodThreshold": 0,
    "allowPickup": true,
    "tier1BaseQty": 0,
    "tier1BasePrice": 0,
    "tier2BaseQty": 0,
    "tier2BasePrice": 0,
    "tier3BaseQty": 0,
    "tier3BasePrice": 0,
    "facebookLink": "",
    "instagramLink": "",
    "twitterLink": "",
    "tiktokLink": "",
    "youtubeLink": "",
    "communityLink": "https://chat.whatsapp.com/example"
}
```

`phoneNumber` and `whatsappNumber` are local numbers of at most 11 characters.

`storeSlogan` is optional, plain text up to 150 characters.

Attach `storeLogo` as an image file (JPG/JPEG/PNG, max 2 MB, minimum 200×150).
It is required when creating store settings and optional when updating.
`storeFooterLogo` is the dark version of the logo for light backgrounds such as the
header (optional; same file rules as `storeLogo`). `get-store-settings` returns it as
`storeFooterLogo`, or `null` until one is uploaded.
`storeSubmarkLogo` is optional (JPG/JPEG/PNG, max 2 MB, minimum 200×200).
When updating, omitting any image retains its existing URL.

### Hero banners

| Endpoint             | Request                                                                                |
| -------------------- | -------------------------------------------------------------------------------------- |
| `save-hero-banner`   | `POST` multipart (fields below); admin auth required. Adds one banner.                 |
| `get-hero-banners`   | `GET`, no body; public. Every banner, oldest first.                                    |
| `delete-hero-banner` | `DELETE`, no body. Path `delete-hero-banner/{id}`; admin auth required. Also removes the image. |

`save-hero-banner` fields, all required:

| Field         | Rules                                                            |
| ------------- | ---------------------------------------------------------------- |
| `heroBanner`  | Image file: JPG/JPEG/PNG, max 3 MB, at least 1500×500, 3:1 ratio |
| `eyebrow`     | Text, max 50 characters (the small line above the headline)      |
| `headline`    | Text, max 100 characters                                         |
| `description` | Text, max 255 characters                                         |
| `ctaText`     | Button text, max 50 characters                                   |
| `ctaLink`     | Button link, max 255 characters                                  |

`save-hero-banner` returns the saved banner; `get-hero-banners` returns a list of them:

```json
{
    "id": 1,
    "heroBanner": "https://cdn.elegance.ng/media/public/banners/20261104101500_ab12cd34.jpg",
    "eyebrow": "New season",
    "headline": "Timeless watches for every occasion",
    "description": "Discover our latest collection.",
    "ctaText": "Shop now",
    "ctaLink": "/collections/watches",
    "createdAt": "04/11/2026 11:15",
    "updatedAt": null
}
```

### Shipping settings

`save-shipping-settings`:

```json
{
    "stateCode": "LA",
    "stateName": "Lagos",
    "deliveryFee": 1500,
    "hasExpress": true,
    "expressDeliveryFee": 2500,
    "hasPod": true,
    "minEta": 1,
    "maxEta": 3,
    "extraNote": "Delivery timelines are business days."
}
```

`update-shipping-settings` uses the same fields and also requires `id`, e.g.:

```json
{
    "id": 1,
    "stateCode": "LA",
    "stateName": "Lagos",
    "deliveryFee": 1500,
    "hasExpress": true,
    "expressDeliveryFee": 2500,
    "hasPod": true,
    "minEta": 1,
    "maxEta": 3,
    "extraNote": "Delivery timelines are business days."
}
```

`expressDeliveryFee`, `hasPod`, `minEta`, `maxEta`, and `extraNote` are optional
on shipping requests. ETA values are integer day counts, and `maxEta` must be
at least `minEta`; omitted settings default to `null`, `false`, `0`, or an empty
string as appropriate.

### Regional shipping settings

```json
{
    "stateId": 1,
    "regionName": "Mainland",
    "deliveryFee": 1800,
    "deliveryTimeline": "1-2 business days",
    "areaList": "Ikeja, Yaba, Surulere",
    "hasPod": true,
    "minEta": 1,
    "maxEta": 2,
    "extraNote": "Delivery timelines are business days."
}
```

Regional `hasPod`, `minEta`, `maxEta`, and `extraNote` are optional. ETA values
are integer day counts, and `maxEta` must be at least `minEta`.

For `update-regional-shipping-settings`, include the record `id` in this body.

### Store policy

`create-store-policy`:

```json
{
    "policyTitle": "Returns and Refunds Policy",
    "policyText": "Returns are accepted within 7 days.",
    "policySlug": "returns"
}
```

Policy text is stored as plain text; HTML tags are stripped and special
characters are encoded by the standard sanitizer.

`update-store-policy`:

```json
{
    "policyId": 1,
    "policyTitle": "Returns and Refunds Policy",
    "policyText": "Returns are accepted within 14 days."
}
```

### Cart

`save-cart` and `update-cart-item`:

```json
{
    "sessionToken": "GST-… (guests only; leave out on the first add)",
    "productId": 1,
    "variantId": 12,
    "quantity": 2
}
```

### Multiple cart items

`add-cart-items`:

```json
{
    "sessionToken": "GST-… (guests only; leave out on the first add)",
    "items": [
        { "productId": 1, "variantId": 12, "quantity": 2 },
        { "productId": 2, "variantId": 21, "quantity": 1 }
    ]
}
```

### Merge cart

```json
{ "sessionToken": "guest-session-token" }
```

### Pickup location

```json
{
    "name": "Lagos Central",
    "address": "1 Example Road",
    "city": "Lagos",
    "state": "Lagos",
    "country": "Nigeria",
    "postalCode": "100001",
    "locationPhoneNumber": "+2348012345678",
    "contactPerson": "Adaeze Okafor",
    "locationDropoffFee": 0,
    "allowPod": true,
    "minEta": 1,
    "maxEta": 2,
    "extraNote": "Call on arrival.",
    "status": "active"
}
```

Pickup `allowPod` and `extraNote` are optional. Pickup `minEta` and `maxEta` are
required integer day counts, and `maxEta` must be at least `minEta`. `status`
is optional and is `active` or `inactive`: new locations default to `active`,
and updates keep the current status when it is omitted. Inactive locations are
hidden from the public endpoints and cannot be used for orders.

### Admin accounts

`update-admin-profile` (own account; name only):

```json
{ "firstName": "Amina", "lastName": "Okafor" }
```

`change-admin-password` (own account):

```json
{
    "currentPassword": "OldPass123!",
    "newPassword": "NewPass456!",
    "confirmPassword": "NewPass456!"
}
```

The new password must meet the password strength rules, match
`confirmPassword` and differ from the current password. A wrong
`currentPassword` returns 401. Changing the password also clears the
default-password flag.

`update-admin/{adminId}` (super admin):

```json
{
    "firstName": "Amina",
    "lastName": "Okafor",
    "email": "amina@example.com",
    "role": "admin"
}
```

`role` is `superadmin`, `manager` or `admin`. Errors: 409 when another admin
already uses the email, when changing your own role, or when demoting the last
active super admin.

`delete-admin/{adminId}` (super admin) is a soft delete: the admin
can no longer sign in, is hidden from `get-all-admins`, and their email address
becomes free to use for a new admin. Activity logs are kept. You cannot delete
your own account or the last active super admin (409). Deleted admins return
404 from `update-admin`, `delete-admin` and `update-status`.

Admin status (`active`, `inactive`, `suspended`) is changed with
[`update-status`](#status-update) using `type: "admin"`.

The profile and password endpoints act on the signed-in admin and return 401
"Authentication required." when no admin is signed in.

### Status update

`update-status` changes the status of one record:

```json
{ "type": "pickup_location", "id": 2, "status": "inactive" }
```

| `type`            | Record                             | Allowed `status`                  |
| ----------------- | ---------------------------------- | --------------------------------- |
| `category`        | Product category                   | `active`, `inactive`              |
| `attribute`       | Category attribute                 | `active`, `inactive`              |
| `variant`         | Product variant                    | `active`, `inactive`              |
| `product`         | Product                            | `draft`, `active`, `archived`     |
| `delivery_state`  | Delivery state (shipping settings) | `active`, `inactive`              |
| `delivery_zone`   | Delivery zone                      | `active`, `inactive`              |
| `pickup_location` | Pickup location                    | `active`, `inactive`              |
| `policy`          | Store policy                       | `active`, `inactive`              |
| `admin`           | Admin account                      | `active`, `inactive`, `suspended` |
| `customer`        | Customer account                   | `active`, `inactive`, `suspended` |

The response data is `{ "type", "id", "status", "previousStatus" }`. Setting
the current status again succeeds without changing anything. Errors: 422 for an
unknown `type`, a status not allowed for that type, or a missing/invalid `id`;
404 when the record does not exist (including soft-deleted products, categories
and customers).

Changing an `admin` requires a super admin. Admins cannot change their own
account, and the last active super admin cannot be deactivated or suspended;
both return 409. Accounts that are not `active` cannot log in; tokens already
issued stay valid until they expire.

Orders, payments and offers are not handled here; use their own endpoints
(offers: `update-limited-time-offer`).

### Create order

`create-order` requires customer authentication. The backend calculates prices,
discounts, delivery fees, and totals; do not send calculated amounts.

Send `deliveryMethod` as `courier` or `pickup`. Each item needs a `productId`,
`variantId`, and positive integer `quantity`. Stock is checked and deducted
atomically when the order is created. For courier delivery, `stateId` is
required and `deliveryZoneId` is optional, along with a `logistics` object
containing the recipient and delivery address. For pickup, provide
`pickupLocationId` and omit `stateId`, `deliveryZoneId`, and `logistics`. The
selected location IDs are stored on the order. An inactive state, delivery
zone, or pickup location is rejected with 422.

`deliveryType` can be `standard` or `express` and defaults to `standard`.
Standard uses the selected zone's fee, or the state's fee when no zone is
selected. Express always uses the state's express fee, with or without a zone,
and is rejected with 422 when the state has express disabled or no express fee.

Standard courier delivery is free when the items total (after discounts) is
above the store's `freeDeliveryThreshold`; express then costs only its
difference from the standard fee that applies (never below 0). A threshold of 0
turns this off. The category extra-quantity fee and pickup drop-off fees still
apply.

`logistics.email` is optional. When it differs from the account email, it gets
a blind copy (BCC) of the customer's order emails; they always go to the
account email.
`courierCost`, `deliveryTimeline`, `courierPartner`, `courierStaff`, and
`courierContact` are not accepted from the client; they are nullable logistics
fields intended to be populated later by an admin. `paymentMethod` must be
`bank_transfer` or `cash_on_delivery`; cash-on-delivery availability depends on
store and shipping settings. `currency` defaults to `NGN`; other currencies are currently rejected.
`customerNote` is optional. A non-empty `voucherCode` is rejected with 422
until voucher redemption is implemented. Bank-transfer orders receive an
account for the full order total. Cash-on-delivery orders receive an account
for the delivery/drop-off fee when that fee is positive; the remaining item
balance is due on delivery. COD orders with no delivery fee do not receive an
account and the full order amount is due on delivery. Pickup orders follow the
same payment-method rules.

```json
{
    "items": [{ "productId": 1, "variantId": 12, "quantity": 3 }],
    "deliveryMethod": "courier",
    "deliveryZoneId": 4,
    "stateId": 1,
    "paymentMethod": "bank_transfer",
    "customerNote": "Please call on arrival.",
    "currency": "NGN",
    "logistics": {
        "contactName": "Amina Okafor",
        "email": "amina@example.com",
        "phone": "+2348012345678",
        "addressLine1": "12 Example Road",
        "addressLine2": null,
        "city": "Lagos",
        "state": "Lagos",
        "country": "Nigeria",
        "postalCode": "100001",
        "nearestLandmark": "Opposite Example Market",
        "deliveryInstructions": "Please call on arrival.",
        "deliveryType": "standard"
    }
}
```

Pickup example:

```json
{
    "items": [{ "productId": 1, "variantId": 12, "quantity": 1 }],
    "deliveryMethod": "pickup",
    "pickupLocationId": 2,
    "paymentMethod": "bank_transfer",
    "logistics": {
        "contactName": "Amina Okafor",
        "email": "amina@example.com",
        "phone": "+2348012345678",
        "addressLine1": "3 Pickup Street",
        "city": "Lagos",
        "state": "Lagos",
        "country": "Nigeria",
        "deliveryType": "standard"
    }
}
```

Both delivery methods require `logistics`, and `contactName`, `email` and `phone` are
required in it. Pickup orders send the same shape as courier orders, filled with the pickup
location's address, but only `contactName`, `email` and `phone` are kept. The saved address,
timeline and note come from the pickup location identified by `pickupLocationId`.

### Confirm payment

`confirm-payment` is called when the payment websocket reports a payment and when
the customer taps "I've paid". It does not contact the payment provider: it adds
up the order's `successful` payments and, for a pending, processing or shipped
order:

- if they cover the order total, sets `paymentStatus` to `paid` and emails the
  order confirmation
- for cash on delivery with a delivery fee, if they cover the fee, sets
  `delivery_paid`; the rest is paid on delivery or into a new account
- otherwise changes nothing

Calling it again is safe; the email is sent once. Cancelled, refunded and failed
orders are never changed (a payment on one is logged for an admin).

```json
{
    "orderNumber": "ORD2611089A1B2C3D",
    "paymentStatus": "paid",
    "isFullyPaid": true,
    "amountPaid": 26500,
    "orderTotal": 26500,
    "balance": 0,
    "updated": true
}
```

`updated` is `true` only on the call that changed `paymentStatus`. `balance` is
what is left of the order total (`0` when paid or overpaid).

### Update order (admin)

`update-order` requires admin authentication and the order ID in the path
(`update-order/{orderId}`). The current handler reads and validates both `status` and
`paymentStatus`, so include both fields in each update. Every update also requires
`adminNote` (up to 255 characters; `422` when missing or longer): it is saved on the order,
and on the status-history entry when the status changes. Customers never see it. Payment statuses
supported by the DTO are `unpaid`, `delivery_paid`, `paid`,
`partially_refunded`, `delivery_refunded`, and `refunded`. `delivery_paid` means
a cash-on-delivery order's delivery fee is paid and the balance is still due; it
is rejected with a 422 for other orders. When setting a courier order to
`shipped`, all courier fields are required:

```json
{
    "status": "shipped",
    "paymentStatus": "paid",
    "courierPartner": "Example Express",
    "courierStaff": "Chinedu Okafor",
    "courierContact": "08012345678",
    "courierCost": 3500,
    "adminNote": "Handed to Example Express at 2pm"
}
```

Delivery `failed` is distinct from payment `failed`. Allowed delivery status
transitions are `pending` -> `processing|cancelled|failed`,
`processing` -> `shipped|cancelled|failed`, `shipped` -> `delivered|failed`, and
`failed` -> `processing|shipped|cancelled`. `delivered`, `cancelled`, and the
legacy `refunded` status are terminal. Refunds should update payment status;
they do not transition delivery status to `refunded`.

Pickup orders follow the same transitions, then `picked_up`: `processing -> shipped ->
delivered -> picked_up`. Shipping a pickup order takes only `courierCost` (any other
courier field is rejected with a 422); `shipped` means it's on its way to the pickup
location, and the customer is emailed that it's on its way there:

```json
{
    "status": "shipped",
    "paymentStatus": "paid",
    "courierCost": 1500,
    "adminNote": "Sent to the Lekki pickup location"
}
```

`delivered` means the order has arrived at the pickup location: the customer is emailed a
6-digit pickup code, with the location's contact person and phone, to show when collecting.
When the customer collects, the admin enters the code they show as `pickupCode` and sets
`picked_up` through `update-order`, from `delivered` only. A wrong code is rejected (422).
`admin-get-order` never shows the code; it returns `pickupCodeVerifiedBy`, the name of the
admin who marked the order picked up (`null` until then, and for courier orders):

```json
{
    "status": "picked_up",
    "pickupCode": "482913",
    "paymentStatus": "paid",
    "adminNote": "Collected by customer, pickup code checked"
}
```

Pickup orders can be reviewed once `picked_up`; courier orders once `delivered`.

Stock is returned only when an order is cancelled (by an admin or the cleanup job).
Marking an order `failed` keeps its stock, so the delivery can be retried. An order
that failed at checkout has already had its stock returned; reopening it (`failed` ->
`processing|shipped`) takes the stock again, or returns `422` naming the SKU that is
short. Cancelling emails the customer a cancellation notice. A `409` means the order
changed since it was loaded (for example, the cleanup job cancelled it): show the
message and reload the order.

Unpaid bank-transfer orders are cancelled automatically 24 hours after being placed,
with stock returned and the customer emailed. Cash on delivery orders are never
auto-cancelled. Cancelled or failed orders that never received a payment are deleted
7 days after closing, so they drop out of order lists.

## Common response shapes

Successful responses use this envelope. `data` is `[]` for handlers that return
only a message; it contains an object or array when the handler returns a
resource. Pagination is included only on paginated endpoints.

```json
{
    "error": false,
    "statusCode": 100,
    "message": "Request completed successfully.",
    "data": []
}
```

Errors sent through `Response::simple()` use this shape; `statusCode` is the
HTTP status:

```json
{
    "error": true,
    "statusCode": 422,
    "message": "Validation error message."
}
```

Product image fields (`image`, `productImage`, `imageUrl`) are `null` when the product has no image; show a placeholder.

## Endpoint response data

The following shows the shape inside the common envelope's `data` field.
Example values are illustrative; field names and nesting follow the current
resources/models.

### Authentication and profiles

- `create-account`, OTP resend/verification, forgot/reset password, change
  password, and `create-admin` return a message with `data: []`.
- `admin-signin` returns an admin object. Regular admins include `publicId`,
  `firstName`, `lastName`, `email`, `role`, and `authentication`; superadmins
  also include `id`, `status`, and `defaultPassword`.
- `admin-get-customers` returns a paginated list, newest first, without deleted customers:
  `[{ "id": "2", "name": "Adeola Johnson", "email": "adeola.johnson@example.com",
"phoneNumber": "+234 801 234 5678", "ordersCount": 4, "totalSpent": 725000,
"dateJoined": "Jan 15, 2024", "dateUpdated": "May 10, 2025, 3:42 PM",
"lastLogin": "May 10, 2025, 3:42 PM", "phone": "+234 801 234 5678",
"gender": "female", "status": "active" }]`. `ordersCount` and `totalSpent`
  leave out cancelled, failed and refunded orders; `lastLogin` is `null` until the
  customer signs in. Pass `id` to `get-customer-analytics`.

### Customer details

`get-customer-analytics` returns:

```json
{
    "customer": {
        "publicId": "1000000002",
        "name": "Adaeze Okafor",
        "status": "active",
        "email": "adaeze.okafor@email.com",
        "phoneNumber": "+234 801 234 5678",
        "location": "Lagos, Nigeria",
        "customerSince": "Apr 12, 2025",
        "totalOrders": 5,
        "totalSpent": 685000,
        "cartItems": 3,
        "lastOrderDate": "May 05, 2025",
        "lastLogin": "May 10, 2025, 3:42 PM",
        "dateJoined": "Apr 12, 2025, 9:15 AM",
        "gender": "Female"
    },
    "recentOrders": [
        {
            "id": "#ORD26102741668940b9",
            "productName": "Tissot Gentleman Watch and 2 more",
            "amount": 320000,
            "date": "May 05, 2025",
            "status": "Delivered",
            "image": "20261027125938_6790d59b9361ae17.jpg"
        }
    ],
    "recentAddress": [
        {
            "houseNumber": "12",
            "street": "Elegance Plaza",
            "city": "Lagos",
            "state": "Lagos",
            "country": "Nigeria"
        }
    ]
}
```

- Dates are Nigerian time. `lastLogin` is `null` until the customer signs in;
  `lastOrderDate` and `location` are `null` with no orders.
- `totalOrders` and `totalSpent` leave out cancelled, failed and refunded orders;
  `totalSpent` is the sum of grand totals (delivery fees included).
- `cartItems` is the total quantity in the customer's cart.
- `recentOrders` holds the 10 latest orders of any status. `productName` is the
  first item's name, with "and N more" for multi-item orders; `image` is the
  first item's product image file name (`null` if the product was deleted).
- `recentAddress` holds up to 5 distinct delivery addresses, most recently used
  first. A leading number in the address line becomes `houseNumber` (otherwise
  `null`, with the whole line in `street`). `location` is the latest address's
  city and country.
- Nigerian phone numbers are shown as `+234 801 234 5678`; others as stored.
- `get-all-admins` returns paginated admin records with `publicId`, `firstName`,
  `lastName`, `email`, and `role`. Password data is not returned.
- User profile update returns `publicId`, `firstName`, `lastName`, `email`,
  `phone`, `gender`, `status`, `authentication`, and `dateCreated`.
  Authentication is empty when no token is being returned.
- `user-signin` returns `publicId`, `firstName`, `lastName`, `email`, `phone`,
  `gender`, `status`, `authentication`, `dateCreated`, and `analytics`, which has
  the same shape as [customer details](#customer-details).

### Categories

`get-category` returns one category object. `get-all-categories` returns an
array of those objects:

```json
{
    "id": 1,
    "name": "Accessories",
    "slug": "accessories",
    "categoryIcon": "fa-kola",
    "categoryImage": "https://example.com/categories/icon.png",
    "categoryBanner": "https://example.com/categories/banner.png",
    "bannerTitle": "New season accessories",
    "description": "Accessories",
    "sortOrder": "0",
    "status": "active",
    "attributeFeatures": ["Size", "Color"],
    "createdAt": "2026-10-19 10:00:00",
    "updatedAt": null,
    "extraQuantityThreshold": 10,
    "additionalShippingFee": 500
}
```

`attributeFeatures` contains the names of active attributes associated with
that category. Categories without active attributes return an empty array.

`get-attributes` returns an array of category-attribute records with
`id`, `categoryId`, and `attributeName`; admins also get `status` and `createdAt`.

### Products

- `create-product`, `update-product`, and `patch-product` return the persisted
  `ProductModel` shape, using database-style field names such as `category_id`,
  `base_price`, and `discount_tier`. Private admin fields include `cost_price`
  and timestamps.
- `get-product` and `admin-get-product` return the nested frontend resource:
  `product`, `discountTier`, `variants`, `features`, `attributes`, and `images`.
  Public `get-product` omits cost price, timestamps, and variant
  `lowStockThreshold`; admin detail includes the private fields.
  Each entry in `attributes` is `{ "name", "value" }` (e.g. `{ "name": "Size",
"value": "Large" }`); admin responses also include the attribute `id`, which
  is what `create-product`/`update-product` expect in their `attributes` list.
- Each variant has `size` (`null` when the product has no sizes). Variants are
  grouped by colour, in the order each colour was first added, with sizes in
  the order they were added; add sizes in the order they should be shown.
  Each image has `colorName`, the colour of its linked variant, or `null` when it
  isn't linked to one; show it for every size of that colour.
- `get-all-products` returns an array of admin product resources and a
  `pagination` object containing `total`, `per_page`, `current_page`,
  `last_page`, `from`, `to`, `has_next`, and `has_prev`.
- `get-featured-products` returns an array of public product resources, the same
  shape as `get-category-products` (`product`, `badge`, `stockStatus`,
  `discountTier`, `variants`, `features`, `attributes`, `specifications`,
  `whatsinbox`, `images`). Private fields such as cost price are not included.
- Offers (`get-active-offers` and the admin offer lists) include
  `product.categoryId`.
- `get-product`, `get-product-by-slug` and `admin-get-product` add `offer` to each variant while a
  limited-time offer is live on it, else `null`. Other product endpoints don't
  include `offer`:

    ```json
    "offer": { "offerPrice": 12000, "startsAt": "01/11/2026 09:00", "endsAt": "10/11/2026 23:59" }
    ```

- Every product resource (the endpoints listed below) and each offer's `product` include
  `rating`: `{ "average": 4.5, "count": 127 }`. `average` is rounded to 1 decimal and is
  `0` when `count` is `0`. Each review belongs to one order item, so it only counts for
  that item's product (hidden reviews are excluded).
- Every product resource (`get-all-products`, `get-product`, `get-product-by-slug`,
  `get-category-products`, `get-featured-products`, `admin-get-product`) has `badge` and `stockStatus` next to
  `product`, each `{ "code", "label" }` or `null`:

    ```json
    "badge": { "code": "best_seller", "label": "Best Seller" },
    "stockStatus": { "code": "low_stock", "label": "Low Stock" }
    ```

    `badge` is the first that applies, in this order (`featured` is set by hand; the rest
    are worked out):

    | Code          | Label                      | When                                                                                                                           |
    | ------------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
    | `featured`    | Featured                   | The product is marked featured (`isFeatured`)                                                                                  |
    | `on_sale`     | On Sale                    | `oldPrice` is higher than `basePrice` (limited-time offers don't count)                                                        |
    | `best_seller` | Best Seller                | One of the 10 top sellers by units in the last 90 days, with at least 3 units (cancelled, failed and refunded orders excluded) |
    | `top_rated`   | Top Rated                  | Average of 4.0 or more from at least 3 visible reviews of the product                                                          |
    | `new`         | New                        | Added in the last 30 days                                                                                                      |
    | `custom`      | _(the `customBadge` text)_ | No automatic badge applies and the product has a `customBadge` (set by an admin)                                               |

    `stockStatus` counts only variants that are switched on (`status: "active"`); a switched-off
    colour doesn't make a product look in stock or out of stock:

    | Code           | Label        | When                                                        |
    | -------------- | ------------ | ----------------------------------------------------------- |
    | `out_of_stock` | Out of Stock | Every active variant has 0 stock                            |
    | `low_stock`    | Low Stock    | Every active variant is at or below its low-stock threshold |

### Limited-time offers

Create/update return an offer object; list endpoints return an array. Offer
fields are `id`, `variantId`, `offerPrice`, `startsAt`, `endsAt`, and `status`,
plus nested `variant` (`id`, `sku`, `colorName`, `colorHex`, `size`) and `product`
(`id`, `name`, `slug`, `sku`, `regularPrice`, `imageUrl`) objects. `startsAt`
and `endsAt` are returned as `dd/mm/YYYY HH:MM` in Nigerian time (UTC+1).

### Store, shipping, and policy settings

- `save-store-settings` and settings mutations return a message with `data: []`.
  `get-store-settings` returns a settings object using camelCase keys such as
  `phoneNumber`, `storeMainLogo`, `storeSubmarkLogo`, `allowPod`,
  `allowPickup`, `createdAt`, and `updatedAt`. `banks` lists the payment bank
  options as `{ "bankCode": "02", "bankName": "Fidelity Bank" }`; send one of
  those `bankCode` values as `paymentBank` when saving, or it is rejected with 422.
- Shipping mutations return a message with `data: []`.
  `get-shipping-settings` returns an array of records with `id`, `state_code`,
  `state`, `state_name`, `delivery_fee`, `express_delivery_fee`, `has_express`, `has_pod`,
  `min_eta`, `max_eta`, `extra_note`, `updated_by`, `status`, `created_at`,
  and `updated_at`.
  `get-regional-shipping-settings` returns a regional record with `state_id`,
  `region_name`, `delivery_fee`, `delivery_timeline`, `area_list`, `has_pod`,
  `min_eta`, `max_eta`, `extra_note`, and status/timestamp fields.
- Store-policy create returns the created policy record; update returns a
  message with `data: []`. `get-store-policy` returns one policy record and
  `get-all-store-policies` returns an array. Policy fields are `id`,
  `policyTitle`, `policySlug`, `policyText`, and `status`; admins also get
  `updatedBy`, `createdAt`, and `updatedAt`.

### Cart and pickup locations

- `save-cart` and `add-cart-items` return `data: { "sessionToken" }` (the
  guest's token, or `null` for a signed-in customer). Cart
  update/delete/clear/merge operations return a message with `data: []`. `get-cart-items` returns an array of cart
  items with `id`, `cartId`, `productId`, `variantId`, `quantity`, `unitPrice`,
  `createdAt`, `updatedAt`, `productName`, `productSku`, `colorName`, `colorHex`,
  `size` and `image` (CDN URL of the variant's image, else the product's main
  image, else its first image; `null` if the product has no images). `get-all-cart-items` groups carts under `customers` (by customer ID)
  and `guests` (by session token); each entry is `{ cart, items }`, where `cart`
  has `id`, `customerId`, `sessionToken`, `status`, `createdAt` and `updatedAt`.
- Pickup create/update/delete operations return a message with `data: []`.
  `get-pickup-location` returns one location object and `get-pickup-locations`
  returns an array. Returned keys are `id`, `name`, `address`, `city`,
  `stateCode`, `state`, `country`, `postalCode`, `locationPhoneNumber`, `contactPerson`,
  `locationDropoffFee`, `allowPod`, `minPodThreshold`, `maxPodThreshold`,
  `minEta`, `maxEta`, `extraNote`, and `status`.

### Orders

`create-order` returns the created order object with `id`, `order_number`,
`customer_id`, delivery method/location IDs, totals, currency, payment method,
`status`, `payment_status`, and timestamps.

The successful response also includes `orderDiscount` (the quantity-tier
discount on items, `discount_total`) and `deliveryDiscount` (the delivery fee
waived by the free-delivery threshold), and `discountTotal`, their sum. All are
`0` when nothing applies. Order details (`get-my-order`, `admin-get-order`, and
the `update-order` response) and order lists (`get-my-orders`,
`admin-get-orders`) return the same three fields. `deliveryFee` is the fee
charged after the waiver, so `grandTotal = subtotal + deliveryFee - orderDiscount`.
To show a breakdown that adds up with `discountTotal`, display the delivery fee
as `deliveryFee + deliveryDiscount`.

The successful response uses the common envelope, with the created order in
`data`. Validation errors use the simple error response shape; common statuses
include `401` for missing/invalid authentication, `404` for a missing referenced
product or delivery setting, `422` for invalid order data, and `500` for
internal failures.

Representative successful response:

```json
{
    "error": false,
    "statusCode": 100,
    "message": "Order created successfully.",
    "data": {
        "id": 101,
        "order_number": "ORD-example",
        "customer_id": 25,
        "delivery_method": "courier",
        "state_id": 1,
        "delivery_zone_id": 4,
        "pickup_location_id": null,
        "delivery_fee": 1500,
        "subtotal": 24000,
        "discount_total": 1500,
        "grand_total": 24000,
        "currency": "NGN",
        "payment_method": "bank_transfer",
        "status": "pending",
        "payment_status": "unpaid",
        "placed_at": "2026-10-15 17:00:00",
        "created_at": "2026-10-15 17:00:00",
        "updated_at": "2026-10-15 17:00:00"
    }
}
```

`update-order` returns `data.order` with that order shape and `data.logistics`
with the logistics record, including `courier_cost`, `courier_partner`,
`courier_staff`, and `courier_contact` (or `null` if no logistics record exists).

### Order lists and details

`get-my-orders` and `admin-get-orders` return a paginated list, newest first.
`productName` is the first item's name, with "and N more" for multi-item orders.
`admin-get-orders` adds `customerId` and `customerName` (both `null` once the
customer is deleted), `paymentMethod` (`null` if none was chosen), `deliveryFee`,
and `deliveryReport`: `{ type, label, dueDate, daysLeft }`. Show `label`.

- `estimate`: unpaid pending/processing orders. `label` is the promised range, e.g. "2–4 business days";
  `dueDate` and `daysLeft` are `null`.
- `countdown`: paid pending, processing and shipped orders (cash on delivery counts from the order date).
  The due date is the payment date plus the latest promised business days; `daysLeft` counts calendar
  days to it (negative once late). `label`: "3 days left", "Due today", "Delayed by 2 days".
- `delivered`: `daysLeft` is days delivered before the due date (negative if after).
  `label`: "Delivered 1 day earlier", "Delivered on time", "Delivered 2 days late".
- `na`: cancelled, refunded and failed orders; `label` is "N/A".

`deliveryReport` is `null` when no delivery estimate is set for the order's pickup location,
delivery region or state.

```json
[
    {
        "orderId": 7,
        "orderNumber": "ORD26102741668940b9",
        "productName": "Tissot Gentleman Watch and 1 more",
        "itemCount": 2,
        "grandTotal": 305000,
        "deliveryMethod": "courier",
        "status": "delivered",
        "paymentStatus": "paid",
        "placedAt": "20/10/2026 10:00",
        "customerId": 15,
        "customerName": "Adaeze Okafor",
        "paymentMethod": "Bank Transfer",
        "deliveryFee": 2500,
        "deliveryReport": {
            "type": "delivered",
            "label": "Delivered 1 day earlier",
            "dueDate": "Nov 05, 2026",
            "daysLeft": 1
        }
    }
]
```

`get-my-order` returns:

```json
{
    "order": {
        "id": 7,
        "orderNumber": "ORD26102741668940b9",
        "customerId": 15,
        "deliveryMethod": "courier",
        "stateId": 1,
        "deliveryZoneId": 4,
        "pickupLocationId": null,
        "deliveryFee": 5000,
        "subtotal": 300000,
        "discountTotal": 0,
        "grandTotal": 305000,
        "currency": "NGN",
        "paymentMethod": "bank_transfer",
        "status": "delivered",
        "paymentStatus": "paid",
        "placedAt": "20/10/2026 10:00",
        "createdAt": "20/10/2026 10:00",
        "updatedAt": "22/10/2026 14:30"
    },
    "deliveryReport": null,
    "deliveryTimeLine": [
        { "status": "pending", "date": "Oct 20, 2026, 10:00 AM" },
        { "status": "processing", "date": "Oct 20, 2026, 11:15 AM" },
        { "status": "shipped", "date": "Oct 21, 2026, 9:40 AM" },
        { "status": "delivered", "date": "Oct 22, 2026, 2:30 PM" }
    ],
    "pickupCode": null,
    "items": [
        {
            "id": 10,
            "orderId": 7,
            "productId": 12,
            "variantId": 31,
            "offerId": null,
            "productName": "Tissot Gentleman Watch",
            "colorName": "Silver",
            "size": null,
            "sku": "TIS-GENT-SLV",
            "unitPrice": 150000,
            "regularPrice": 150000,
            "quantity": 1,
            "lineTotal": 150000,
            "image": "https://cdn.elegance.ng/media/20261027130132_c5aab64af8c68ce9.jpg",
            "createdAt": "20/10/2026 10:00",
            "review": {
                "id": 1,
                "orderId": 7,
                "orderItemId": 10,
                "rating": 4,
                "review": "Lovely watch, quick delivery.",
                "orderDate": "23/10/2026 09:12"
            }
        }
    ],
    "logistics": {
        "id": 4,
        "orderId": 7,
        "contactName": "Adaeze Okafor",
        "contactPhone": "08012345678",
        "addressLine1": "5 Admiralty Way",
        "addressLine2": null,
        "city": "Lagos",
        "state": "Lagos",
        "country": "Nigeria",
        "postalCode": null,
        "nearestLandmark": null,
        "deliveryInstructions": null,
        "deliveryType": "standard",
        "courierCost": null,
        "deliveryTimeline": null,
        "courierPartner": null,
        "courierStaff": null,
        "courierContact": null,
        "createdAt": "20/10/2026 10:00",
        "updatedAt": "20/10/2026 10:00"
    }
}
```

For pickup orders, `logistics` holds the pickup location saved at checkout (its address,
`deliveryTimeline` and note as `deliveryInstructions`), plus `pickupLocation`, `contactPerson`
and `contactPersonPhone`. The contact is the location's current one; if the location has
been deleted, it's the one saved at checkout. Orders placed before this change have
`logistics: null`. Each item's `review` is `null` until the
customer reviews that item.

`deliveryTimeLine` lists the order's status changes, oldest first, as `{ status, date }`
(without the admin's notes). Orders placed before the timeline was recorded show one entry with their
current status. `items[].image` is the variant's image (matched on SKU), else the product's
main image, or `null`.

`pickupCode` is the 6-digit code the customer shows to collect a pickup order. It's set only
while the order is `delivered` (waiting at the pickup location) and is `null` otherwise,
including after it's `picked_up`. It's a plain string; keep any leading zeros (e.g. `"048213"`).

`deliveryReport` works as in [order lists](#order-lists-and-details): `{ type, label, dueDate, daysLeft }`,
or `null` when no delivery estimate is set.

### Admin order details

`admin-get-order` returns:

```json
{
    "orderId": "ORD2610063f1a2b9c7d",
    "orderDate": "Oct 06, 2026 10:30 PM",
    "status": "delivered",
    "pickupCodeVerifiedBy": null,
    "deliveryReport": null,
    "itemsCount": 3,
    "total": 27300,
    "subtotal": 27500,
    "shippingDifference": -2700,
    "subtotalProfit": 7500,
    "totalProfit": 4800,
    "deliveryFee": 1800,
    "discount": 2000,
    "paymentReference": "TRX-0001-2",
    "paymentDate": "Oct 06, 2026 11:05 PM",
    "paymentMethod": "bank_transfer",
    "paymentBankName": "Access Bank",
    "accountCredited": "9000000001",
    "paymentStatus": "paid",
    "customer": {
        "id": "15",
        "name": "Adeola Johnson",
        "email": "adeola@example.com",
        "phoneNumber": "+234 701 000 0001"
    },
    "shipping": {
        "deliveryPartner": "GIG Logistics",
        "deliveryPartnerId": "gig-logistics",
        "dispatcherName": "John Doe",
        "dispatcherPhone": "+234 803 111 2222",
        "firstName": "Adeola",
        "lastName": "Johnson",
        "phoneNumber": "+234 701 000 0001",
        "houseNumber": "12",
        "street": "Admiralty Way",
        "city": "Lekki",
        "state": "Lagos",
        "country": "Nigeria",
        "nearestLandmark": "Near the main gate",
        "method": "Standard Delivery",
        "zone": "Lekki Phase 1",
        "fee": 1800,
        "courierFee": 4500,
        "instructions": "Call before delivery."
    },
    "deliveryTimeLine": [
        { "status": "processing", "date": "Oct 07, 2026, 12:30 AM", "adminNote": "Payment confirmed." },
        { "status": "shipped", "date": "Oct 07, 2026, 10:30 PM", "adminNote": "Handed to GIG." },
        { "status": "delivered", "date": "Oct 09, 2026, 10:30 PM", "adminNote": null }
    ],
    "items": [
        {
            "id": "41",
            "name": "Tissot Gentleman Watch",
            "slug": "tissot-gentleman-watch",
            "basePrice": 7500,
            "quantity": 1,
            "total": 7500,
            "profits": 2500,
            "variants": {
                "id": "31",
                "title": "Silver",
                "colorName": "Silver",
                "size": null,
                "sku": "TIS-GENT-SLV",
                "colorHex": "#C0C0C0",
                "image": "https://…/tissot-silver.jpg"
            }
        },
        {
            "id": "42",
            "name": "Casio Edifice",
            "slug": "casio-edifice",
            "basePrice": 10000,
            "quantity": 2,
            "total": 20000,
            "profits": 7000,
            "variants": {
                "id": "33",
                "title": "Black",
                "colorName": "Black",
                "size": null,
                "sku": "CAS-EDF-BLK",
                "colorHex": "#000000",
                "image": "https://…/casio-black.jpg"
            }
        }
    ],
    "paymentHistory": [
        {
            "amount": 13650,
            "paymentReference": "TRX-0001-2",
            "paymentBankName": "Access Bank",
            "accountCredited": "9000000001",
            "paymentDate": "Oct 06, 2026 11:05 PM"
        },
        {
            "amount": 13650,
            "paymentReference": "TRX-0001-1",
            "paymentBankName": "Access Bank",
            "accountCredited": "9000000001",
            "paymentDate": "Oct 06, 2026 10:40 PM"
        }
    ]
}
```

- `basePrice` is the price the customer paid (the offer price during a limited-time offer).
  `profits` is `(basePrice − cost price) × quantity`, using the cost price saved when the
  order was placed (the product's current cost for older orders).
- `subtotalProfit` is the sum of item `profits` minus `discount`. `shippingDifference` is
  `deliveryFee − courierFee` for courier orders (it can be negative) and `0` for pickup.
  `totalProfit` is `subtotalProfit + shippingDifference`.
- `paymentReference` and `paymentDate` come from the latest successful payment. Before any
  payment is recorded, `paymentReference` is the payment account reference and `paymentDate` is `null`.
- `paymentHistory` lists successful payments, newest first (empty until one is recorded).
  `paymentBankName` and `accountCredited` are the order's payment account.
- `customer` is `null` once the customer is deleted. For pickup orders, `shipping` shows the
  pickup location saved at checkout with `method: "Pickup"`; `dispatcherName`/`dispatcherPhone`
  are the location's current contact person and phone. Orders placed before this change have
  `shipping: null`.
- `deliveryReport` works as in [order lists](#order-lists-and-details): `{ type, label, dueDate, daysLeft }`,
  or `null` when no delivery estimate is set.
  `deliveryPartnerId` is a slug of `deliveryPartner`. Courier fields are `null` until the order ships.
- `deliveryTimeLine` is oldest first. Orders placed before the timeline was recorded show
  one entry with their current status. Each entry's `adminNote` is the note the admin sent
  with that status update (`null` if none). Customers' timelines don't include it.
- `admin-get-order` doesn't include the review; use `admin-get-reviews`.

### Reviews

`create-review` and `get-reviews` return:

```json
{
    "id": 1,
    "orderId": 7,
    "orderItemId": 10,
    "rating": 4,
    "review": "Lovely watch, quick delivery.",
    "orderDate": "23/10/2026 09:12"
}
```

`get-reviews` returns a paginated list of these, newest first, visible reviews only.
`orderDate` is the date the review was written.

`get-product-reviews` returns a paginated list of one product's visible reviews, newest first:

```json
{
    "id": 1,
    "rating": 4,
    "review": "Lovely watch, quick delivery.",
    "colorName": "Silver",
    "colorHex": "#C0C0C0",
    "size": null,
    "image": "https://cdn.elegance.ng/media/public/products/20261112132809_60f625e62db614a4.png",
    "customerName": "Adaeze O.",
    "createdAt": "23/10/2026 09:12"
}
```

`colorName` and `size` are what was bought (`size` is `null` for products without sizes). `customerName` is the reviewer's first name and last
initial, and is `null` if the customer was deleted.

`image` is the reviewed variant's image (matched by variant or SKU); if that variant has none, an image of the same colour; otherwise the
product's main image. It is `null` if the product has no images.

The product details response (`get-product`, `get-product-by-slug`) also includes `reviews`: `averageRating`, `items` (page 1, the 10 newest,
in the shape above) and `pagination` in the usual shape. When `pagination.has_next` is true, load more with `get-product-reviews` from
page 2 (`get-product-reviews/{productId}/2`); it also returns 10 per page.

```json
"reviews": {
    "averageRating": 4.2,
    "items": [ /* up to 10 reviews */ ],
    "pagination": {
        "total": 14,
        "per_page": 10,
        "current_page": 1,
        "last_page": 2,
        "from": 1,
        "to": 10,
        "has_next": true,
        "has_prev": false
    }
}
```

`admin-get-reviews` returns a paginated list of every review, hidden ones included,
newest first:

```json
{
    "id": 1,
    "productSlug": "tissot-gentleman-automatic",
    "productName": "Tissot Gentleman Automatic Watch",
    "productImage": "20261027125938_6790d59b9361ae17.jpg",
    "productCategory": "Watches",
    "orderId": "ELG-1028",
    "rating": 5,
    "review": "Keeps impeccable time. Delivered to Lekki in less than 24 hours.",
    "status": 1,
    "createdAt": "Sep 12, 2025, 02:40 PM",
    "customer": {
        "id": "1029384756",
        "name": "Adeola Johnson",
        "email": "adeola.johnson@example.com"
    }
}
```

- Each review belongs to one order item, and the product fields describe that item.
  If that product was deleted, `productName` is the name saved on the order and
  `productSlug`, `productImage` and `productCategory` are `null`.
- `orderId` is the order number (accepted by `admin-get-order`). `status` is 1 visible,
  0 hidden. `createdAt` is when the review was written. `productImage` is a full URL, or `null` when the product has no image.
- `customer.id` is the customer's `publicId`; `customer` is `null` if the customer was deleted.

`get-my-reviews` returns a paginated list of the signed-in customer's reviews, newest first, in the same shape
without `customer`. Hidden reviews are included; `status` 0 means the store has hidden it, so show it as not published.

`admin-get-reviews` also returns `meta.stats`, counted over all reviews (not just
the current page):

```json
"meta": { "stats": { "totalReviews": 6, "averageRating": 4.2, "published": 5, "unpublished": 1 } }
```

`published` and `unpublished` count visible (`status` 1) and hidden (`status` 0)
reviews. `averageRating` is rounded to one decimal place and is `0` when there are
no reviews.

### Admin dashboard

`get-system-analytics` returns:

```json
{
    "stats": {
        "totalRevenue": 3450000,
        "revenueGrowth": 18.2,
        "totalOrders": 1200,
        "ordersGrowth": 12.5,
        "totalCustomers": 5000,
        "customersGrowth": 8.4,
        "conversionRate": 3.4,
        "conversionGrowth": 0.8,
        "lowStockCount": 15,
        "outOfStockCount": 3,
        "averageOrderValue": 2875,
        "averageOrderValueGrowth": 5.1,
        "grossProfit": 910000,
        "profitMargin": 28.4,
        "awaitingPaymentCount": 4,
        "awaitingPaymentAmount": 96500,
        "averageRating": 4.2
    },
    "ordersByStatus": {
        "pending": 12,
        "processing": 8,
        "shipped": 5,
        "delivered": 1160,
        "cancelled": 9,
        "refunded": 2,
        "failed": 4
    },
    "salesTrend": [
        { "month": "Dec 2025", "revenue": 210000, "orders": 74 },
        { "month": "Nov 2026", "revenue": 45000, "orders": 15 }
    ],
    "recentOrders": [
        {
            "orderId": "ELG-SEED-0008",
            "orderDate": "Oct 30, 2026",
            "status": "pending",
            "orderTotal": 18550,
            "customerName": "Tunde Adeyemi"
        }
    ],
    "topProducts": [
        {
            "productId": 3,
            "productName": "Classic Leather Watch",
            "productImage": "uploads/products/watch.jpg",
            "totalSalesCount": 100,
            "totalRevenue": 5000
        }
    ],
    "lowStockItems": [
        {
            "productId": 5,
            "productName": "Silver Bracelet",
            "colorName": "Silver",
            "size": null,
            "sku": "SB-SLV",
            "stockQuantity": 0,
            "lowStockThreshold": 5
        }
    ]
}
```

- Counted orders are all orders except `cancelled`, `failed` and `refunded`. `totalRevenue`,
  `totalOrders`, `averageOrderValue`, `grossProfit`, `salesTrend` and `topProducts` use counted
  orders only. `recentOrders` shows the 5 latest orders of any status.
- Totals are all-time. Each `…Growth` compares this calendar month so far with all of last month,
  in Nigerian time, as a percentage. It is `null` when last month was 0. `customersGrowth`
  compares new signups.
- `conversionRate` is the share of carts whose customer later placed a counted order.
  `conversionGrowth` is this month's rate minus last month's, in percentage points (by cart
  creation date), and `null` when last month had no carts.
- `grossProfit` is item price less cost, times quantity, less order discounts; delivery fees are
  not included. `profitMargin` is that profit as a percentage of goods sold (subtotal less
  discounts).
- `awaitingPayment…` counts pending, unpaid orders that aren't cash on delivery.
- `lowStockCount` counts active variants at or below their low-stock threshold, including those
  out of stock; `outOfStockCount` counts those at 0. `lowStockItems` lists the 5 lowest.
- `salesTrend` covers the last 12 months, oldest first, including months with no orders.
- `orderId` in `recentOrders` is the order number; `productImage` is the stored path.
- `orderTotal` in `recentOrders` is the order's grand total (after discounts, delivery included).
