BOB Docs
APIApplication

Subscription

API

The application is accessible via the following endpoint:

/api/subscription/*

The API facilitates subscription management, including initiating new subscriptions and updating existing ones.

SubscriptionInteractor

The SubscriptionInteractor serves as the core business logic layer for managing subscription-related operations. It integrates various services to streamline plan management, subscription checkout, and user permissions.

Key Features

  1. Plan Management:
    • Retrieves available subscription plans with pagination for easy user display.
  2. Checkout Process:
    • Manages the creation of checkout sessions, ensuring valid billing data and customer eligibility.
  3. Subscription Updates:
    • Processes changes in subscriptions and updates user permissions based on the selected plan.
  4. Organization Subscriptions:
    • Fetches all subscriptions linked to a user’s organization.
  5. Billing Validation:
    • Ensures customers have valid billing data before initiating the checkout process.
  6. Trial Period Handling:
    • Determines trial period eligibility for subscription plans based on customer criteria.

Methods

  1. Plan Management:

    • get_available_plans_paginated: Retrieves paginated subscription plans available for purchase.

  2. Checkout Process:

    • checkout: Creates a checkout session for purchasing a subscription, validating billing and eligibility.

  3. Subscription Updates:

    • process_subscription_changes: Updates user permissions when a subscription is modified.

  4. Organization Subscriptions:

    • get_organization_subscriptions: Retrieves paginated subscriptions linked to a user’s organization.

Example Workflow

1. Retrieve Available Plans

Fetch subscription plans available for users.

plans, pagination = await subscription_interactor.get_available_plans_paginated(page_number=1, page_size=8)

2. Initiate Checkout

Create a checkout session for a selected subscription plan.

checkout_url = await subscription_interactor.checkout(user, pricing_id=123)

3. Process Subscription Updates

Handle changes to a subscription and update associated user permissions.

await subscription_interactor.process_subscription_changes(subscription_id=456)

Dependencies

  • Services Used:
    • CustomerService: Manages customer data and associations.
    • BillingService: Validates and handles billing information for customers.
    • PaymentService: Creates and manages payment sessions for subscriptions.
    • ProductService: Ensures products meet eligibility criteria for subscriptions.
    • PlanService: Handles subscription plan details and trial periods.
    • SubscriptionService: Manages subscription lifecycle events and data.
    • UserService: Retrieves user-related data for subscription operations.
    • PermissionService: Updates user permissions based on subscription plans.

Example Scenario

Subscription Purchase Flow

  1. User views plans:
  • Plans are retrieved using get_available_plans_paginated and displayed to the user.
  1. User selects a plan:
  • A checkout session is initiated via checkout, allowing the user to proceed with payment.
  1. Subscription activation:
  • Once payment is completed, process_subscription_changes updates the user’s permissions and finalizes the subscription setup.

Commands

The setupsubscription command automates the initialization of subscription plans and their associated data. It streamlines the process of creating plans, linking them with products, permission groups, and pricing configurations, based on predefined settings.

Key Features

  1. Automated Initialization:

    • Creates subscription plans and their associated entities (e.g., products, pricing, images, translations) from the configuration.

  2. Multi-Entity Handling:

    • Links subscription plans with permission groups and products in a single operation.

  3. Trial Period Management:

    • Configures trial periods and free subscription allowances for plans.

  4. Batch Processing:

    • Processes multiple plans from the configuration for scalable and efficient initialization.

Workflow

  1. Load Configuration:

    • Reads subscription plan details from the PLANS_CONFIGURATION setting.

  2. Create Plans:

    • Uses PlanService.create_plan to set up each plan, linking it with products and permission groups.

  3. Apply Settings:

    • Configures trial period days, pricing models, and availability as defined in the configuration.

  4. Completion:

    • Logs progress and success messages for each step of the setup process.

Example Configuration

PLANS_CONFIGURATION = [
    {
        "key": "Premium",
        "trial_period_days": 14,
        "amount_of_free_subscriptions": 2,
        "tax_code": "txcd_2002001",
        "pricing": [
            {"interval": PriceInterval.MONTH, "unit_amount": 1500},
            {"interval": PriceInterval.YEAR, "unit_amount": 15000}
        ],
        "images": [
            {
                "image_path": "/path/to/premium.png",
                "title": "Premium Plan Image"
            }
        ],
        "translation": {
            "en": {
                "name": "Premium Plan",
                "checkout_description": "Enjoy the premium features.",
                "description": "Access advanced features with our premium plan.",
                "statement_descriptor": "Premium Subscription"
            }
        }
    }
]

Example Execution

Run the following command in the terminal to initialize subscription plans:

python manage.py setupsubscription

Dependencies

  • Services:
    • PlanService: Creates and manages subscription plans.
  • Settings:
    • PLANS_CONFIGURATION: Defines the configuration for subscription plans.

Benefits

  • Efficiency:
  • Speeds up the initialization of subscription plans by automating the process.
  • Consistency:
  • Ensures all plans are configured as per the predefined settings.
  • Scalability:
  • Handles multiple plans efficiently, making it ideal for large configurations.

Signals

The subscription_post_save signal is triggered when a Subscription instance is saved. It ensures automatic updates to subscription-related settings, such as permissions and trial usage. The signal invokes the process_subscription_changes method in SubscriptionInteractor for post-save operations.

Models

Plan

The Plan model represents subscription plans available for organizations. Key features include:

  • Associations:
  • Links to a Product and a Group for permission-based features.
  • Configurations:
  • Includes trial periods (trial_period_days), user limits (users_amount), and availability flags.
  • Uniqueness:
  • Ensures no duplicate plans exist through unique constraints.
  • Fields:
  • key: Identifier for the plan.
  • trial_period_days: Free trial duration for the plan.
  • users_amount: Maximum number of users allowed.

Subscription

The Subscription model tracks an organization's active subscription. Key features include:

  • Associations:
  • Links to a Plan and organization details.
  • Billing Cycle:
  • Tracks billing_cycle_anchor, trial_start, and trial_end timestamps.
  • Fields:
  • status: Subscription status (e.g., active, canceled).
  • trial_start, trial_end: Trial period timestamps.
  • Properties:
  • Converts Unix timestamps to human-readable datetime values.

TrialUsage

The TrialUsage model enforces trial restrictions for users. Key features include:

  • Unique Identifier:
  • Uses an email_checksum to uniquely track trial usage while maintaining privacy.
  • Enforcement:
  • Prevents users from exploiting trial offers by creating new accounts.
  • Fields:
  • email_checksum: Unique hashed identifier for a user.
  • Indexing:
  • Optimized for quick lookups and trial enforcement.

This model ensures fair usage of trial periods across the system.

Previous

ProductService

Next

PlanService

On this page