Membership products (Admin)

Executive summary

The admin screen Packages manages rows in the membership_products table with audience platform_vendor: quota-style entitlements for vendor accounts (stores, products, staff, devices, customers, orders), not store customer loyalty programs.

Route and UI

/dashboard/membership-products — list, search, status filter, pagination, create / edit / delete.
/dashboard/membership-subscriptions — read-only subscription list for platform vendors only (platform_vendor) for support/audit workflows.
/dashboard/membership-invoices — invoice-style view for vendor package purchases (derived from platform_vendor subscriptions with paid/unpaid status).
/dashboard/membership-invoices/:id — invoice detail page with Download invoice action (text export).
benefits_json is edited via structured quota fields in the modal: max_stores, max_products, max_pos_devices, max_staff_seats, max_customers, max_orders. Saving writes those rows only (legacy module_unlock / feature_flag rows are not re-emitted). The API validates with parseAndValidateMembershipBenefitsJson (membership-benefits-json helpers).
Code auto-generation: when creating a plan and code is blank, backend auto-generates a unique code.
Delete guard: deleting a plan is blocked when it is linked to vendors (derived from membership_subscriptions.membership_product_id).
Detail screen: shows linked vendors (search + pagination), plan details, and Member perks (benefits_json).

Optional: link to this doc from the admin UI

Set VITE_PUBLIC_DOCS_BASE_URL in apps/admin-web (no trailing slash) to the public Starlight origin, e.g. https://docs.example.com. The membership plan modal then shows an Open documentation link to /guides/admin/membership-products/.

Authentication

AdminJwtAuthGuard on GET/POST/PATCH/DELETE /admin/membership-products.
Any signed-in admin with a valid JWT can call these routes (no extra module guard on the controller). Zone or role limits for “who may edit SaaS plans” are a product decision — if tightened later, document the new guard here.

APIs (web client)

Implemented in apps/admin-web/src/services/admin-membership-products.api.ts (base path is the usual API prefix, e.g. /api/v1, via shared Axios config):

Method	Path	Purpose
GET	`/admin/membership-products`	List (`page`, `limit`, `search`, `status`)
GET	`/admin/membership-products/:id`	Detail
POST	`/admin/membership-products`	Create
PATCH	`/admin/membership-products/:id`	Update
DELETE	`/admin/membership-products/:id`	Delete
GET	`/admin/membership-subscriptions`	List vendor subscriptions / invoices (`page`, `limit`, `search`, `status`, `payment_status`, `vendor_id`, `user_id`)
GET	`/admin/membership-subscriptions/:id`	Membership invoice detail by subscription id

Vendor self-serve checkout flow (used by Vendor Web platform-membership screen):

Method	Path	Purpose
GET	`/vendor/membership-products/platform-packages/list`	List active `platform_vendor` catalog packages
POST	`/vendor/membership-products/platform-packages/:id/purchase`	Create/reuse pending invoice (`past_due`) for package
GET	`/vendor/membership-products/platform-invoices`	List package-purchase invoices for current vendor
GET	`/vendor/membership-products/platform-invoices/:id`	Invoice detail for current vendor
POST	`/vendor/membership-products/platform-invoices/:id/pay`	Mark invoice as paid and activate subscription

New rows created from this surface are stored with audience = platform_vendor and vendor_id / store_id unset at the catalog level (SaaS plan definition).

Difference from vendor “customer membership”

Surface	Audience	Who it is for
Admin — this page	`platform_vendor`	Vendor accounts (SaaS)
Vendor — Membership products (Vendor)	`vendor_customer`	End customers of a store

Admin panel overview
Vendor membership products — customer programs
Regenerate the machine endpoint list: cd apps/backend && npm run openapi:export (updates technical/backend-api-catalog)