Billing, Plans, and Subscriptions
Relevant source files
The following files were used as context for generating this wiki page:
Casdoor includes a comprehensive management system for commercial offerings, enabling administrators to define features, pricing structures, and manage user access through subscriptions. This system allows Casdoor to function as a subscription management platform where plan features are tied to Casdoor roles and permissions.
Sources: web/src/TourConfig.js:77-87
Architecture and Data Model
The billing system is structured around three primary entities: Plans, Pricings, and Subscriptions. These entities interact to define what is sold, how much it costs, and who has access to it.
Entity Relationships
The following diagram illustrates the relationship between the core billing components:
The diagram shows that an Organization owns multiple Plans and Pricings. Pricings are collections of Plans. Each Plan is associated with a Role (granting permissions) and a Product. Subscriptions link a User to a specific Plan following a Payment.
Sources: web/src/PlanListPage.js:34-45, web/src/PricingListPage.js:32-41, web/src/SubscriptionListPage.js:33-45, swagger/swagger.yml:1430-1483
Data Structures
| Entity | Key Fields | Purpose |
|---|---|---|
| Plan | name, price, currency, period, role, product | Describes application features (via roles) and their standalone cost. |
| Pricing | name, application, plans, trialDuration | A group of plans presented to a specific application, including trial settings. |
| Subscription | user, plan, startTime, endTime, state | Tracks an individual user's active access to a plan's features. |
Sources: swagger/swagger.yml:1430-1483, web/src/PlanListPage.js:34-45
Plan Management
Plans are the building blocks of the commercial offering. They describe a set of features (via a Casdoor Role) and a price point.
Key Attributes
- Role: The Casdoor role that a user acquires when the plan is active. This role contains the set of permissions defined in the Casbin model.
- Period: Typically "Monthly" or "Yearly".
- Product: A related product entity used for checkout and payment processing.
- Exclusivity: Plans can be marked as exclusive, preventing concurrent subscriptions.
Sources: web/src/PlanListPage.js:34-45, web/src/TourConfig.js:83-87, swagger/swagger.yml:1430-1450
Pricing Configurations
Pricing objects act as the "Storefront" configuration. They determine which plans are available to which applications and define promotional periods like trials.
Workflow: Selecting a Plan
When a user visits a pricing page, the following logic is executed:
- The system fetches the Pricing configuration for the specific Application.
- It retrieves the details for all Plans linked to that Pricing.
- Users can toggle between different periods (e.g., Monthly vs Yearly) if multiple plan types exist.
- If a user is logged in, they are redirected to a checkout URL (
/buy-plan/...); if not, they are sent to the signup page.
Sources: web/src/pricing/PricingPage.js:63-145, web/src/PricingEditPage.js:140-155
Subscription Lifecycle
Subscriptions represent the realization of a plan for a user. They govern the "Active" status of a user's permissions.
Subscription States
Subscriptions transition through various states defined in the backend:
| State | Description |
|---|---|
| Pending | Subscription created but awaiting payment verification. |
| Active | User currently has access to the plan features/roles. |
| Upcoming | Subscription scheduled to start in the future. |
| Expired | The endTime has passed; access is revoked. |
| Suspended | Access manually revoked by an administrator. |
| Error | An issue occurred during processing or renewal. |
Sources: web/src/SubscriptionListPage.js:161-177, swagger/swagger.yml:1473-1483
Date Logic
Subscriptions utilize startTime and endTime. In the UI, a new subscription defaults to a 30-day window from the current time if the period is "Monthly".
Sources: web/src/SubscriptionListPage.js:40-41, web/src/SubscriptionEditPage.js:130-145
API Endpoints
The billing system is managed through standard RESTful endpoints.
| Action | Plan Endpoint | Pricing Endpoint | Subscription Endpoint |
|---|---|---|---|
| Add | POST /api/add-plan | POST /api/add-pricing | POST /api/add-subscription |
| Get | GET /api/get-plan | GET /api/get-pricing | GET /api/get-subscription |
| Update | POST /api/update-plan | POST /api/update-pricing | POST /api/update-subscription |
| Delete | POST /api/delete-plan | POST /api/delete-pricing | POST /api/delete-subscription |
| List | GET /api/get-plans | GET /api/get-pricings | GET /api/get-subscriptions |
Sources: swagger/swagger.yml:254-290, swagger/swagger.yml:685-715, swagger/swagger.yml:1185-1215
Conclusion
The Casdoor Billing and Subscription module provides a flexible bridge between identity management and commercialization. By linking Plans to Roles, the system ensures that access control is automatically synchronized with a user's subscription status. Administrators can configure these offerings through the web UI using the Pricing and Plan management pages, while the Subscription lifecycle handles the ongoing validity of user access.