> ## Documentation Index
> Fetch the complete documentation index at: https://system.muzemus.online/llms.txt
> Use this file to discover all available pages before exploring further.

# Order approval

> The approval workflow for store-submitted uniform orders

## Approval workflow

```mermaid theme={null}
sequenceDiagram
    actor SM as Store Manager / HR
    actor HR as HR user
    participant API as NestJS API
    participant DB as PostgreSQL
    participant Email as Email Service

    SM->>API: POST /api/v1/orders (rule set requires approval)
    API->>DB: INSERT Order (status PENDING_APPROVAL)
    API->>Email: "Requires your approval" to HR
    HR->>API: PATCH /api/v1/orders/:id/approve
    API->>API: Check ORDERS_APPROVE permission + scope
    API->>DB: UPDATE Order SET status = APPROVED
    API->>DB: Append OrderStatusHistory
    API->>Email: Notify the submitter
```

## Who can approve

Only roles holding the `orders.approve` permission can approve orders:

| Role           | Can approve? |
| -------------- | ------------ |
| SUPER\_ADMIN   | Yes          |
| MUZE\_ADMIN    | Yes          |
| HR             | Yes          |
| STORE\_MANAGER | No           |

## Approval flow

1. **Order is placed** with items and sizes. If the matched rule set requires approval, the order is stored with status `PENDING_APPROVAL`; otherwise it submits directly as `SUBMITTED`.
2. **HR or an admin reviews** the order (in-app notification and email, with the Sales Order PDF attached) and either:
   * **Approves**, moving it to `APPROVED`, or
   * **Rejects** with a required reason, moving it to `REJECTED`.
3. **Pending orders can be edited** before approval: items, quantities, and sizes can be modified, and the entitlement split is recalculated on save.

## Rejection handling

* The status moves to `REJECTED` (terminal).
* The reason is stored on the order (`rejectedReason`) and recorded in `OrderStatusHistory`.
* No entitlement is consumed by a rejected order; the submitter can view the reason and place a corrected order.

## Entitlement impact

Entitlement consumption is recorded per order item against the employee's active entitlement period (see [Entitlement engine](/business-engines/entitlement-engine)):

| Event                                        | Entitlement effect                                |
| -------------------------------------------- | ------------------------------------------------- |
| Order placed (PENDING\_APPROVAL / SUBMITTED) | No consumption yet                                |
| Order approved                               | Consumption committed within the same transaction |
| Order rejected                               | No consumption                                    |
| Order cancelled after consumption            | Consumed quantity released                        |

## Email notifications

| Event                               | Recipient               | Content                                 |
| ----------------------------------- | ----------------------- | --------------------------------------- |
| Order submitted (approval required) | HR users for the client | Review link + Sales Order PDF           |
| Order submitted                     | Administrators          | Informational copy with Sales Order PDF |
| Order approved / rejected           | Submitter               | Status update, rejection reason if any  |

Email delivery is best-effort and never blocks the order transition: notifications (in-app and email, including Sales Order PDF generation) are dispatched in the background after the transaction commits. See [Notifications](/notifications-reports/notifications).

## Scoping

The `ScopeGuard` ensures:

* A Store Manager can only place orders for their own store
* An HR user can only approve orders within their client
* Admins can approve across all clients