> ## Documentation Index
> Fetch the complete documentation index at: https://memberpulseptyltd.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Membership Plans
> Create and configure membership plans with pricing, benefits, and billing options
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:
* **Plan Name** - Display name (e.g., "Professional Member")
* **Description** - Plan benefits and features
* **Status** - Active, Inactive, or Archived
* **Price** - Base price amount
* **Billing Cycle** - Monthly or Annual
* **Tax Inclusion** - Whether price includes tax
* **Discount Price** - Optional promotional price
* **Automatic Discount %** - Percentage off for specific conditions
* **Free Event Tickets** - Number of complimentary tickets per year
* **Resource Access** - Level of resource library access
* **Course Access** - LMS course availability
* **Directory Listing** - Business directory inclusion
* **Custom Benefits** - Free-text benefit descriptions
* **Grace Period** - Days allowed after expiry (default: 7)
* **Proration** - Enable/disable mid-cycle changes
* **Auto-Renewal** - Default renewal setting
* **Required CPD Points** - Points required for certification/compliance (spreadsheet mentions `MembershipPlan.requiredCpdPoints`)
#### 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
Enter plan name and description. Choose whether the plan is public (visible to new members) or internal only.
Configure price, billing cycle, and any discounts. Specify if tax is included in the displayed price.
Add the benefits included with this plan. Use the benefits builder to add structured benefits or free-text descriptions.
Set grace period, proration rules, and default renewal behavior.
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
Editing a plan affects all current members on that plan. Price changes only apply to new subscriptions and renewals, not current billing periods.
#### 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
```typescript theme={null}
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" |