Subscriptions Overview

The subscriptions module provides a comprehensive system for managing recurring revenue through periodic billing. It handles various subscription models from monthly memberships to annual passes, with flexible pricing, beneficiaries support, and seamless integration with the billing system for automated invoice generation.

Core Concepts

Subscription Types: Define the recurring service offerings with billing periods, pricing, and associated products. Each type can have different periodicities from single payments to annual billing cycles.

Subscription Customers: Individual customer subscriptions with custom pricing overrides, start/end dates, and payment preferences. Tracks active status and manages the lifecycle of each subscription.

Beneficiaries: Additional customers who benefit from a subscription without being the primary payer. Common in family memberships or corporate subscriptions.

Add-ons: Optional products or services that can be attached to subscriptions with fixed or percentage-based pricing. Support accumulative pricing and date ranges.

Automated Billing: Daily cron job or manual triggers generate invoices based on subscription periods, with support for proration, custom billing dates, and payment method preferences.

Main Database Tables

Core Subscription Structure

┌─────────────────┐         ┌───────────────────┐         ┌─────────────┐
│  Subscription   │────────▶│SubscriptionType   │────────▶│   Product   │
│     Type        │         │    Customer       │         │  (billing)  │
└────────┬────────┘         └─────────┬─────────┘         └─────────────┘
         │                            │
         │                            │ beneficiaries
         │                            ▼
         │                  ┌───────────────────┐         ┌─────────────┐
         │                  │   Subscription    │────────▶│  Customer   │
         │                  │   Beneficiary     │         └─────────────┘
         │                  └───────────────────┘
         │
         │ temporary suspension
         ▼
┌─────────────────┐
│  Subscription   │ (alternative during pause)
│     Type        │
└─────────────────┘

Billing Generation Flow

┌───────────────────┐         ┌─────────────┐         ┌─────────────┐
│  Subscription     │────────▶│    Sale     │────────▶│   Invoice   │
│    Customer       │         │  (billing)  │         │  (optional) │
└─────────┬─────────┘         └──────┬──────┘         └─────────────┘
          │                          │
          │ add-ons                  │ payment
          ▼                          ▼
┌───────────────────┐         ┌─────────────┐         ┌─────────────┐
│  Subscription     │         │   Payment   │────────▶│   Payment   │
│     Add-on        │         │  (billing)  │         │   Method    │
└───────────────────┘         └─────────────┘         └─────────────┘

Task Management System

    Manual Trigger / Cron Job (6 AM daily)
                   │
                   ▼
         ┌───────────────────┐
         │ SubscriptionTask  │ (tracks progress)
         └─────────┬─────────┘
                   │
                   │ batch processing
                   ▼
         ┌───────────────────┐         ┌─────────────┐
         │  Generate Sales   │────────▶│  EditedSale │ (custom amounts)
         │   for Period      │         └─────────────┘
         └─────────┬─────────┘                │
                   │                          │
                   │ skip dates               │
                   ▼                          ▼
         ┌───────────────────┐         ┌─────────────┐
         │  Check Omitted    │◀────────│ OmittedSale │
         │      Dates        │         └─────────────┘
         └───────────────────┘

Core Entities

• subscription: Subscription type definitions with periods, pricing, and rules
• subscriptionCustomer: Active customer subscriptions with custom settings
• subscriptionBeneficiary: Secondary beneficiaries of subscriptions
• subscriptionAddon: Additional products attached to subscriptions
• subscriptionTask: Background task tracking for bulk operations

Billing Control

• editedSale: Override amounts for specific billing dates
• omittedSale: Skip billing on specific dates
• cancellationReason: Standardized reasons for subscription cancellations

Subscription Lifecycle

1. Creation: Customer subscribes to a type with optional custom pricing
2. Active Period: Regular billing based on configured period
3. Modifications: Add beneficiaries, apply add-ons, edit specific dates
4. Temporary Suspension: Switch to alternative subscription during breaks
5. Cancellation: End subscription with reason tracking and tag cleanup

Billing Periods

The system supports various billing frequencies:

Single Payment (0)   ───────────────────────▶ One-time charge

Monthly (1)          ─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─┬─▶ 12 times/year

Bi-monthly (20)      ───┬───┬───┬───┬───┬───▶ 6 times/year

Quarterly (30)       ─────┬─────┬─────┬─────▶ 4 times/year

Semi-annual (60)     ───────────┬───────────▶ 2 times/year

Annual (120)         ───────────────────────▶ 1 time/year

Key Features

Flexible Pricing: Base product pricing with customer-specific overrides and dynamic pricing integration.

Proration Support: First period can be prorated based on start date, with options for actual days or fixed 30-day months.

Beneficiary Management: Multiple beneficiaries per subscription with automatic tag assignment.

Add-on System: Flexible additional charges with percentage-based, fixed, or accumulative pricing models.

Automated Processing: Daily cron job generates invoices automatically with configurable timing and batch sizes.

Payment Integration: Automatic charge attempts using configured payment methods with fallback options.

Tag Management: Automatic customer tagging for subscription holders and beneficiaries.

Temporary Suspensions: Support for vacation holds with alternative subscription types.

Business Rules

• Subscriptions are considered active between start and end dates (end date can be null for ongoing)
• Billing generation checks for existing sales to prevent duplicates
• Proration only applies to the first billing period
• Add-ons can have date ranges for temporary charges
• Cancellation removes customer and beneficiary tags automatically
• Direct debit preferences are stored per subscription
• Custom pricing overrides the base product price
• Omitted dates skip billing entirely for that period

Billing Generation Process

1. Date Calculation: Determines next billing date based on period and last invoice
2. Price Determination: Uses custom price or product price with tax calculations
3. Proration Logic: Calculates partial period charges for new subscriptions
4. Add-on Processing: Applies fixed, percentage, or accumulative add-on charges
5. Sale Creation: Generates billing sale with proper references and descriptions
6. Payment Processing: Attempts automatic payment if configured
7. Invoice Generation: Creates invoices if enabled in settings

API Integration

The subscriptions module exposes APIs for:

• Managing subscription types and configurations
• Adding/removing customers and beneficiaries
• Processing billing runs manually or via scheduled tasks
• Handling temporary suspensions and cancellations
• Generating reports and billing summaries
• Managing date-specific overrides and exclusions
• Bulk operations through background tasks

Configuration Settings

Key system settings that control subscription behavior:

• Cron Job Enable: Activate automatic daily billing generation
• Auto Payment Method: Default payment method for automatic charges
• Generate Invoices: Automatically create invoices for subscription sales
• Fixed Days Apportionment: Use 30-day months for proration calculations
• Period Limit: Maximum billing period for manual generation (security feature)

This system provides a robust foundation for any business model requiring recurring revenue management, from simple monthly memberships to complex multi-tier subscription services with flexible billing rules and comprehensive automation capabilities.