# Feature: Packages & entitlements

Corporate benefit plans — allowance, co-pay, categories, perks, caps, exclusions, and per-member overrides.

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

## Pages

| Route | Purpose |
|-------|---------|
| `/packages` | Package list with search/status filter |
| `/packages/new` | Create corporate package (allowance, co-pay, categories, perks) |
| `/packages/[id]` | Package detail/edit — rules, assigned members |
| `/me` | Member view of assigned package + allowance (see member-experience) |

## Entities

- [`Package`](../backend/entities/package.md)
- [`Member.overrides`](../backend/entities/member.md)

## Endpoints

- [`packages.md`](../backend/endpoints/packages.md)
- `GET /v1/me/package` — member allowance view

## Package structure

| Component | Purpose |
|-----------|---------|
| Allowance | Monthly/quarterly/annual cap per member |
| Co-pay % | Member pays remainder on covered items |
| Category rules | Coverage % per product category (chronic, OTC, etc.) |
| Perks | Custom benefits (free delivery, priority dispense) |
| Caps | Max order amount, orders/month, Rx fills/month |
| Exclusions | Blocked SKUs or categories |

## Status lifecycle

```
draft → active → archived
```

Pending orgs: packages saved as `draft` only until Admin activates org.

## Per-member overrides

Set on member detail (`/members/[id]`):

- Allowance cap override
- Co-pay override
- Extra categories or perks
- Exclusions

Overrides layer on top of base package at entitlement calculation time.

## Validation / errors

| Scenario | Code |
|----------|------|
| Duplicate package code | `DUPLICATE_PACKAGE` |
| Archive with assigned members | `PACKAGE_IN_USE` |
| Activate while org pending | `ORG_PENDING` |
| No category rules | `VALIDATION_FAILED` |

## Clinical withhold

Packages define coverage rules only — visible to all roles. No patient data.

## Checkout integration

Remaining allowance computed from:

```
allowance_remaining = package.allowance - allowance_used + overrides
```

Displayed on B2B `/me`. Actual basket split at checkout is **Ecom** — see [`gishen-ecom.md`](../coordination/gishen-ecom.md).

## UI components

- Package list cards/table with status badges
- Detail form: allowance input, co-pay slider, category rule builder, caps section
- Assigned members tab with reassign action

## Related

- [migration.md](migration.md) — bulk package import
- [finance.md](finance.md) — spend by category reflects package rules