# Entity: Package

Corporate benefit plan defining allowance, co-pay, covered categories, perks, caps, and exclusions.

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

## Fields

| Field | Type | Required | Notes |
|-------|------|----------|-------|
| `id` | `string` | ✓ | `pkg_*` |
| `org_id` | `string` | ✓ | |
| `name` | `string` | ✓ | e.g. "Gold Executive" |
| `code` | `string` | ✓ | Unique per org; used in imports |
| `description` | `string` | | HR-facing |
| `status` | `PackageStatus` | ✓ | |
| `allowance` | `PackageAllowance` | ✓ | |
| `copay_percent` | `number` | ✓ | 0–100; member pays remainder |
| `categories` | `CategoryRule[]` | ✓ | Covered product categories |
| `perks` | `Perk[]` | | Custom perks |
| `caps` | `PackageCaps` | | |
| `exclusions` | `Exclusion[]` | | SKU/category blocks |
| `member_count` | `integer` | | Assigned members |
| `created_at` | `Timestamp` | ✓ | |
| `updated_at` | `Timestamp` | ✓ | |
| `version` | `integer` | ✓ | |

### PackageStatus

```
draft | active | archived
```

Pending orgs: packages may be saved as `draft` but cannot be `active` until org activation (configurable; default: block).

### PackageAllowance

| Field | Type | Notes |
|-------|------|-------|
| `amount` | `Money` | Monthly allowance per member |
| `period` | `AllowancePeriod` | |
| `rollover` | `boolean` | Unused rolls to next period |

```
AllowancePeriod = monthly | quarterly | annual
```

### CategoryRule

| Field | Type |
|-------|------|
| `category_code` | `string` |
| `coverage_percent` | `number` | 0–100 |
| `max_per_order` | `Money` \| null |

### Perk

| Field | Type |
|-------|------|
| `code` | `string` |
| `label` | `string` |
| `description` | `string` |

Example perks: `free_delivery`, `priority_dispense`, `annual_checkup_voucher`.

### PackageCaps

| Field | Type |
|-------|------|
| `max_order_amount` | `Money` |
| `max_orders_per_month` | `integer` |
| `max_rx_fills_per_month` | `integer` |

### Exclusion

| Field | Type |
|-------|------|
| `type` | `sku` \| `category` |
| `ref` | `string` |
| `reason` | `string` |

## Validation rules

| Rule | Error code |
|------|------------|
| `code` unique per org | `DUPLICATE_PACKAGE` |
| `copay_percent` 0–100 | `VALIDATION_FAILED` |
| Cannot archive package with active members without reassignment | `PACKAGE_IN_USE` |
| At least one category rule | `VALIDATION_FAILED` |

## Clinical withhold

Packages define **coverage rules**, not patient clinical data. Safe for all roles.

## Sample payload

```json
{
  "id": "pkg_01HGOLD",
  "org_id": "org_01HQXYZ",
  "name": "Gold Executive",
  "code": "GOLD",
  "description": "Full chronic + acute coverage with 10% co-pay",
  "status": "active",
  "allowance": {
    "amount": { "amount": "15000.00", "currency": "ETB" },
    "period": "monthly",
    "rollover": false
  },
  "copay_percent": 10,
  "categories": [
    { "category_code": "chronic", "coverage_percent": 100, "max_per_order": null },
    { "category_code": "otc", "coverage_percent": 80, "max_per_order": { "amount": "500.00", "currency": "ETB" } }
  ],
  "perks": [
    { "code": "free_delivery", "label": "Free delivery", "description": "On all orders" }
  ],
  "caps": {
    "max_order_amount": { "amount": "10000.00", "currency": "ETB" },
    "max_orders_per_month": 10,
    "max_rx_fills_per_month": 4
  },
  "exclusions": [
    { "type": "category", "ref": "cosmetics", "reason": "Not covered" }
  ],
  "member_count": 128,
  "created_at": "2026-01-01T00:00:00Z",
  "updated_at": "2026-02-01T00:00:00Z",
  "version": 5
}
```

## Related endpoints

- [`../endpoints/packages.md`](../endpoints/packages.md)