Membership Plans

Create and manage membership plans that define pricing tiers, benefits, and billing cycles for your organization.

Capabilities

Action	ROLE_CLIENT_ADMIN	ROLE_CLIENT_USER
View plans	✅	✅
Create plans	✅	❌
Edit plans	✅	❌
Archive plans	✅	❌
Set pricing	✅	❌

Features

Plan Configuration

Each membership plan includes:

Acceptance Criteria

Frontend

• Plans list displays all membership plans with key details
• Create plan wizard with step-by-step configuration
• Preview how plan appears to members
• Member count shown per plan
• Drag-and-drop benefit ordering
• Price calculator showing tax-inclusive/exclusive amounts

Backend / API

• Backend behavior supports this feature as documented.

Permissions

• Access is restricted per the Capabilities matrix on this page (or equivalent role rules).

Business Rules

• Plan names must be unique within organization
• Price must be greater than 0 (or 0 for free plans)
• At least one active plan must exist
• Billing cycle cannot be changed for plans with active subscriptions
• Grace period: 0-30 days allowed

Error Handling

• Error states return clear messages and appropriate HTTP status codes.

Plan Change Workflows (Upgrade / Downgrade / Billing Period)

Membership Plans define what members can purchase and renew into, but member plan changes are a separate workflow.

Supported changes:

• Upgrade: move to a higher plan immediately (optionally prorated)
• Downgrade: schedule a downgrade to take effect at the next renewal (no mid-cycle downgrade by default)
• Switch billing period: switch between monthly and annual pricing for the same plan family

Billing period switching rules:

• Switching monthly → annual can be immediate (prorated) or scheduled at renewal (configurable)
• Switching annual → monthly is typically scheduled at renewal to avoid refunds/partial periods (configurable)

Proration rules (configurable per client):

• Proration is calculated from remaining time in the current paid period
• Proration can be disabled for simpler accounting (then changes apply at renewal)

Acceptance Criteria

Frontend

• Members can view available plans and billing periods (monthly/annual) and see the price difference.
• Upgrade flow clearly shows effective date and any proration charge/credit.
• Downgrade flow clearly indicates the change will apply at renewal (unless configured otherwise).
• Billing period switch flow clearly indicates effective date and any proration charge/credit.

Backend / API

• Backend supports upgrades, scheduled downgrades, and billing period switches (immediate or scheduled).

Permissions

• Only members (or client admins acting on behalf of a member) can initiate plan changes for that member.

Business Rules

• Downgrades default to applying at renewal.
• If proration is enabled, proration calculations are deterministic and auditable.
• A member cannot have two active membership subscriptions at the same time.

Error Handling

• If a plan change cannot be applied (invalid status, unpaid invoice, etc.) the UI shows a clear reason and next step.

Create New Plan

1. Basic Information

   Enter plan name and description. Choose whether the plan is public (visible to new members) or internal only.

2. Set Pricing

   Configure price, billing cycle, and any discounts. Specify if tax is included in the displayed price.

3. Define Benefits

   Add the benefits included with this plan. Use the benefits builder to add structured benefits or free-text descriptions.

4. Configure Billing

   Set grace period, proration rules, and default renewal behavior.

5. Review & Publish

   Review all settings and activate the plan to make it available.

Acceptance Criteria

Frontend

• UI supports the workflows described in this feature.

Backend / API

• Backend behavior supports this feature as documented.

Permissions

• Access is restricted per the Capabilities matrix on this page (or equivalent role rules).

Business Rules

• All business rules for this feature are enforced.

Error Handling

• Error states return clear messages and appropriate HTTP status codes.

Edit Existing Plan

Acceptance Criteria

Frontend

• Edit plan form with all configurable fields

Backend / API

• Backend behavior supports this feature as documented.

Permissions

• Access is restricted per the Capabilities matrix on this page (or equivalent role rules).

Business Rules

• All business rules for this feature are enforced.

Error Handling

• Error states return clear messages and appropriate HTTP status codes.

Archive Plan

Archived plans:

• Are hidden from new member signup
• Continue for existing members until renewal
• Can be restored if needed

Acceptance Criteria

Frontend

• Archive confirmation with impact summary

Backend / API

• Backend behavior supports this feature as documented.

Permissions

• Access is restricted per the Capabilities matrix on this page (or equivalent role rules).

Business Rules

• Cannot delete plan with active members (archive instead)

Error Handling

• Error states return clear messages and appropriate HTTP status codes.

Implementation Contracts

Backend (API)

GET    /api/membership-plans                 # List all plans
POST   /api/membership-plans                 # Create new plan
GET    /api/membership-plans/{id}            # Get plan details
PUT    /api/membership-plans/{id}            # Update plan
DELETE /api/membership-plans/{id}            # Archive plan
GET    /api/membership-plans/{id}/members    # List members on plan
POST   /api/membership-plans/{id}/duplicate  # Clone plan

# Member plan changes
POST   /api/members/{memberId}/membership/change-plan
POST   /api/members/{memberId}/membership/schedule-downgrade
POST   /api/members/{memberId}/membership/change-billing-period

Data Model

interface MembershipPlan {
  id: string;
  name: string;
  description: string;
  priceType: 'monthly' | 'annually';
  price: number;
  taxInclusion: boolean;
  discountPrice?: number;
  automaticDiscountPercentage?: number;
  benefits: string[];
  freeEventTickets: number;
  gracePeriodDays: number;
  requiredCpdPoints?: number;
  prorationEnabled: boolean;
  status: 'active' | 'inactive' | 'archived';
  createdAt: string;
  updatedAt: string;
}

Error Handling

Error	HTTP Status	Message
Duplicate name	409	"A plan with this name already exists"
Invalid price	400	"Price must be a positive number"
Has active members	400	"Cannot delete plan with active members"
Last active plan	400	"At least one active plan must exist"