Subscription Management
Full lifecycle management for tenant subscriptions with multi-currency pricing, promotional discounts, upgrade/downgrade impact analysis, trials, expiry handling, and comprehensive analytics export.
Subscriptions are the bridge between tenants and editions. They define which plan a tenant is on, when it starts and expires, and how the system behaves when the subscription lifecycle changes. With built-in multi-currency pricing and promotional discount tracking, SCRIPE provides everything you need for monetization.
Subscription Lifecycle
Every subscription follows a well-defined state machine. The system automatically enforces valid transitions and emits domain events at each stage for audit and integration purposes.
Subscription Types
| Type | Duration | Use Case |
|---|---|---|
| Standard | Fixed period with expiry date | Regular commercial subscriptions |
| Trial | Short-term evaluation period | Free trials that auto-convert or expire |
| Add-on | Supplementary to main subscription | Additional feature packs (e.g., extra storage) |
Key Operations
Assign Subscription
Link a tenant to an edition with start date, duration, currency, optional promo code, and auto-renewal configuration.
Upgrade Plan
Move a tenant to a higher edition. New features are available immediately and the subscription period can be adjusted.
Downgrade Plan
Move to a lower edition. The system provides a full impact analysis showing which features will be lost before confirming.
Impact Analysis
Before any downgrade, the API returns a detailed analysis of affected features and current usage — preventing surprise data loss.
Expiry Behavior
| Policy | Behavior | Use Case |
|---|---|---|
| Grace Period | Features remain active for N days after expiry | Give customers time to renew |
| Immediate Block | Features disabled the moment subscription expires | Strict quota enforcement |
| Fallback Edition | Automatically downgrade to the default (free) edition | Freemium models with paid upgrades |
Enterprise Subscription Management
Immutable Renewal Audit Trail
Renewals create NEW subscription rows instead of overwriting existing records. Each billing cycle preserves locked-in pricing for precise MRR trends, churn analysis, and financial audit compliance.
Intelligent Promotion Expiry
Time-bound promotions are automatically tracked via PromotionExpiresAt. Expired promotions are stripped on renewal — new pricing takes effect seamlessly without admin intervention.
Race-Condition Protection
Optimistic concurrency stamps on every subscription prevent mid-air collisions between parallel operations. Enterprise-grade data integrity without performance penalties.
Pipeline-Level Validation
All 8 subscription commands are guarded by FluentValidation validators with fully localized error messages in English and Arabic. Invalid requests are rejected before business logic executes.
Cross-Module Admin Integration
Subscription lifecycle events automatically cascade to Identity management. When suspended, all tenant admins are deactivated. On resume, only subscription-suspended admins are reactivated.
API Endpoints
| Method | Endpoint | Description | Auth |
|---|---|---|---|
| GET | /api/subscriptions | List all subscriptions | 🔒 Required |
| POST | /api/subscriptions/assign | Assign subscription to tenant | 🔒 Required |
| PUT | /api/subscriptions/{id}/upgrade | Upgrade subscription edition | 🔒 Required |
| PUT | /api/subscriptions/{id}/downgrade | Downgrade subscription edition | 🔒 Required |
| GET | /api/subscriptions/{id}/downgrade-impact | Analyze downgrade impact | 🔒 Required |
| PUT | /api/subscriptions/{id}/suspend | Suspend subscription | 🔒 Required |
| PUT | /api/subscriptions/{id}/reactivate | Reactivate subscription | 🔒 Required |
| PUT | /api/subscriptions/{id}/cancel | Cancel subscription | 🔒 Required |