# Endpoints: Packages

Corporate benefit plan CRUD and member assignment helpers.

**Workspace:** `/Users/kirukib/Desktop/Yaltopia Project/Gishen-B2B`

**Entity:** [`../entities/package.md`](../entities/package.md)

---

## GET /v1/packages

List packages.

| | |
|---|---|
| **Auth** | Required |
| **Roles** | SUPER_USER, HR_ADMIN, FINANCE (read), MEMBER (own assignment via `/v1/me/package`) |

### Query

`?page=1&status=active&q=gold`

### Response 200

Paginated [`Package`](../entities/package.md) list.

---

## POST /v1/packages

Create package.

| | |
|---|---|
| **Auth** | Required |
| **Roles** | SUPER_USER, HR_ADMIN |

### Request

```json
{
  "name": "Silver Standard",
  "code": "SILVER",
  "description": "Standard employee coverage",
  "allowance": {
    "amount": { "amount": "8000.00", "currency": "ETB" },
    "period": "monthly",
    "rollover": false
  },
  "copay_percent": 15,
  "categories": [
    { "category_code": "chronic", "coverage_percent": 90, "max_per_order": null }
  ],
  "caps": {
    "max_order_amount": { "amount": "5000.00", "currency": "ETB" },
    "max_orders_per_month": 8,
    "max_rx_fills_per_month": 3
  },
  "exclusions": [],
  "perks": [],
  "status": "draft"
}
```

### Response 201

Created package.

### Errors

| Code | HTTP | When |
|------|------|------|
| `DUPLICATE_PACKAGE` | 409 | Code exists |
| `ORG_PENDING` | 422 | Cannot activate until org active |
| `VALIDATION_FAILED` | 400 | |

---

## GET /v1/packages/:id

Package detail.

| | |
|---|---|
| **Auth** | Required |
| **Roles** | SUPER_USER, HR_ADMIN, FINANCE; MEMBER if assigned |

### Response 200

Full package including assigned `member_count`.

---

## PATCH /v1/packages/:id

Update package.

| | |
|---|---|
| **Auth** | Required |
| **Roles** | SUPER_USER, HR_ADMIN |

### Notes

- Setting `status: "active"` requires org `active`.
- Archiving blocked if members assigned without reassignment.

### Errors

| Code | HTTP |
|------|------|
| `PACKAGE_IN_USE` | 422 |

---

## DELETE /v1/packages/:id

Archive package (`status: archived`).

| | |
|---|---|
| **Auth** | Required |
| **Roles** | SUPER_USER, HR_ADMIN |

---

## GET /v1/packages/:id/members

Members assigned to package.

| | |
|---|---|
| **Auth** | Required |
| **Roles** | SUPER_USER, HR_ADMIN |

### Response 200

Paginated member summary (id, name, employee_id, status).

---

## GET /v1/me/package

Member's assigned package + allowance (member portal).

| | |
|---|---|
| **Auth** | Required |
| **Roles** | MEMBER, SUPER_USER (when viewing as member) |

### Response 200

```json
{
  "data": {
    "package": { "id": "pkg_01HGOLD", "name": "Gold Executive", "code": "GOLD", "...": "..." },
    "allowance_summary": {
      "allowance_total": { "amount": "15000.00", "currency": "ETB" },
      "allowance_used": { "amount": "4200.00", "currency": "ETB" },
      "allowance_remaining": { "amount": "10800.00", "currency": "ETB" }
    },
    "overrides": null
  }
}
```

---

## UI routes

| Route | Endpoint(s) |
|-------|-------------|
| `/packages` | GET `/v1/packages` |
| `/packages/new` | POST `/v1/packages` |
| `/packages/[id]` | GET/PATCH + activate/deactivate mock |
| `/me` | GET `/v1/me/package` |

## Clinical withhold

Packages contain coverage rules only — safe for all roles.

## Checkout note

Remaining allowance displayed in B2B member UI; **entitlement split at checkout** is implemented in Gishen-Ecom — see [`../../coordination/gishen-ecom.md`](../../coordination/gishen-ecom.md).