Gishen-B2B/docs/backend/endpoints/packages.md

Endpoints: Packages

Corporate benefit plan CRUD and member assignment helpers.

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

Entity: ../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 list.

---

POST /v1/packages

Create package.

Auth	Required
Roles	SUPER_USER, HR_ADMIN

Request

{
  "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

{
  "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.