> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://apidocs.nms.go.ug/llms.txt.
> For full documentation content, see https://apidocs.nms.go.ug/llms-full.txt.

# Order Lifecycle

> Understand the distinct lifecycles for Program and EMHS orders, including specific statistics prerequisites.

# Order Lifecycle

The NMS API supports two primary ordering workflows, each driven by different data inputs: **Program Orders** and **EMHS Orders**. While they share a similar approval flow, their prerequisites and creation processes differ significantly based on the order type.

## Workflow Overview

```mermaid
graph TD
    subgraph "Program Orders (Statistics Driven)"
        PS[Submit Statistics] --> PO[Create Program Order]
    end

    subgraph "EMHS Orders (Procurement Plan Driven)"
        PP[Procurement Plans] --> EO[Create EMHS Order]
    end

    PO --> S[Submit for Review]
    EO --> S
    S --> R[First-Level Review]
    R --> A[Final Approval]
    A --> F[NMS Fulfillment]
```

***

<Tabs>
  <Tab title="Program Orders">
    ### Program Orders (Statistics Driven)

    Program Orders are scheduled orders for essential health programs. Most program orders (except LAB) require the submission of specific **Patient Statistics** templates before the corresponding order can be placed.

    #### Order to Statistics Mapping

    Each program order type is linked to specific statistics templates. You must submit all required stats for a given order type before creating the order.

    | Order Type                   | Required Statistics Templates    |
    | :--------------------------- | :------------------------------- |
    | **ARV**                      | `ARV-ADULT`, `ARV-OI`, `ARV-PED` |
    | **HIV TEST KITS**            | `HIV` Statistics                 |
    | **RH** (Reproductive Health) | `RH` Statistics                  |
    | **ANTI-TB**                  | `TB` Statistics                  |
    | **MDR-TB**                   | `MDR-TB` Statistics              |
    | **LAB**                      | *None (Exception)*               |

    #### 1. Prerequisite: Submit Required Statistics

    Before creating a Program Order, submit the required statistics based on the mapping above. Each statistic has its own template identifier.

    ```bash title="Submit Statistics (e.g., ARV-ADULT)"
    curl -X POST https://testapi.nms.go.ug/api/v1/stats/submit \
      -H "Authorization: Bearer $TOKEN" \
      -d '{
        "templateCode": "ARV-ADULT",
        "hfCode": "HF0124",
        "financialYear": "2023/2024",
        "cycle": "1",
        "data": [...]
      }'
    ```

    #### 2. Create Order (Draft)

    Once all required statistics for the order type are submitted, create the draft order:

    ```bash title="POST /api/v1/orders/program"
    curl -X POST https://testapi.nms.go.ug/api/v1/orders/program \
      -H "Authorization: Bearer $TOKEN" \
      -d '{
        "hfCode": "HF0124",
        "orderType": "ARV",
        "financialYear": "2023/2024",
        "cycle": "1",
        "items": [...]
      }'
    ```

    The response returns a `templateCode` used for the subsequent approval steps.
  </Tab>

  <Tab title="EMHS Orders">
    ### EMHS Orders (Procurement Plan Driven)

    EMHS orders are specialized orders for facilities under the Essential Medicines and Health Supplies framework. These are driven by **Procurement Plans** generated by NMS.

    #### 1. Prerequisite: Retrieve Procurement Plan

    Facilities must first fetch their assigned procurement plans to find the relevant `planIdentifier`:

    ```bash title="Get Facility Procurement Plans"
    curl -X GET "https://testapi.nms.go.ug/api/v1/orders/procurement-plans/facility/HF0124?financialYear=2023/2024" \
      -H "Authorization: Bearer $TOKEN"
    ```

    #### 2. Create EMHS Order

    Use the `planIdentifier` and items from the procurement plan to create the EMHS order:

    ```bash title="POST /api/v1/orders/emhs"
    curl -X POST https://testapi.nms.go.ug/api/v1/orders/emhs \
      -H "Authorization: Bearer $TOKEN" \
      -d '{
        "hfCode": "HF0124",
        "planIdentifier": "PLAN-789",
        "items": [...]
      }'
    ```
  </Tab>
</Tabs>

***

## Universal Approval Flow

Once an order (Program or EMHS) is created in **Draft** status, it follows this universal approval lifecycle:

### 1. Submit for Review

Transition the order from `DRAFT` to `SUBMITTED`.

```bash title="POST /api/v1/orders/{type}/.../submit"
curl -X POST "https://testapi.nms.go.ug/api/v1/orders/program/{templateCode}/submit" \
  -H "Authorization: Bearer $TOKEN"
```

### 2. First-Level Review

A supervisor or NMS officer reviews and advances the order to `REVIEWED`.

```bash title="POST /api/v1/orders/{type}/.../review?approve=true"
curl -X POST "https://testapi.nms.go.ug/api/v1/orders/program/{templateCode}/review?approve=true" \
  -H "Authorization: Bearer $TOKEN"
```

### 3. Final Approval

The order is authorized for fulfillment and moves to `APPROVED`.

```bash title="POST /api/v1/orders/{type}/.../approve?approve=true"
curl -X POST "https://testapi.nms.go.ug/api/v1/orders/program/{templateCode}/approve?approve=true" \
  -H "Authorization: Bearer $TOKEN"
```

<Note>
  The `templateCode` is used for Program Orders, while EMHS orders typically use the `planIdentifier` or an internal order ID in their specific lifecycle paths. Refer to the [API Reference](/api-reference) for the exact path structures for each order type.
</Note>