Skip to main content

Subscription & Billing

This document provides a detailed overview of the subscription and billing system implemented in the backend services. It describes the main entities, services, and workflows related to subscription management, plan management, and invoicing.

Overview​

The subscription and billing module handles:

  • User subscription management (creation, update, activation, revocation, deletion)
  • Plan management (create, update, delete, list)
  • Invoice management (automatic invoice generation, retrieval, PDF generation)
  • Pricing calculation (subscription + optional VPS costs)

It ensures that users can subscribe to plans, switch plans, and receive accurate billing information for their subscriptions and hosted services.

Entities​

The system revolves around the following core entities:

Subscription​

  • Represents a user's subscription to a specific plan.
  • Fields:
    • subscriptionId: unique identifier
    • user: the subscribed user
    • plan: the plan subscribed to
    • price: price of the subscription
    • startDate / endDate: subscription period
    • nextBillingDate: next billing date
    • active: status of the subscription
  • Relationships:
    • One-to-One with User
    • One-to-One with Invoice
    • One-to-One with Plan

Plan​

  • Represents a subscription plan with pricing and features.
  • Fields:
    • planId: unique identifier
    • name: plan name
    • price: plan price
    • billingCycle: monthly or yearly
    • features: optional features list
    • recommended: flag for recommended plans
    • active: status
  • Relationships:
    • One-to-Many with Subscription

Invoice​

  • Represents billing information generated for a subscription.
  • Fields:
    • invoiceId: unique identifier
    • invoiceNumber: formatted as INV-{YEAR}-{COUNT}
    • subscription: associated subscription
    • subscriptionPrice: subscription cost
    • vpsPrice: total VPS cost from user's projects/services
    • amount: total amount (subscription + VPS)
    • issueDate: date of invoice
    • paid: invoice payment status
  • Relationships:
    • One-to-One with Subscription

Services​

SubscriptionService​

Responsible for subscription lifecycle management:

Key Methods:​

  • createSubscription(SubscriptionRequest request)

    • Creates a subscription for a user.
    • Checks if the user already has an active subscription.
    • Assigns plan, start date, price, and calculates end date based on the billing cycle.
    • Automatically generates the first invoice via InvoiceService.

  • getSubscriptionByUserId(String userId)

    • Retrieves subscription details for a specific user.

  • updateSubscription(Long subscriptionId, SubscriptionRequest request)

    • Updates the plan, price, and end date of an existing subscription.

  • deleteSubscription(Long subscriptionId)

    • Deletes a subscription.
    • First removes any associated invoices to maintain referential integrity.

  • changeUserSubscriptionPlan(String userId, Long newPlanId)

    • Switches the user to a new plan.
    • Updates price and end date accordingly.

  • revokeSubscription(String userId)

    • Revokes (terminates) an active subscription.
    • Deletes subscription entity and removes association from user.

  • activateSubscription(String userId)

    • Reactivates an inactive subscription and recalculates the end date.

  • Helper: calculateEndDate(Plan plan)

    • Calculates subscription end date based on billing cycle (MONTHLY/YEARLY).

PlanService​

Handles subscription plan CRUD operations:

Key Methods:​

  • createPlan(PlanRequest request) – Create a new subscription plan.
  • updatePlan(Long planId, PlanRequest request) – Update plan details.
  • deletePlan(Long planId) – Delete a plan.
  • getPlanById(Long planId) – Retrieve plan details.
  • getAllPlans() – List all available plans.

InvoiceService​

Manages billing and invoice generation:

Key Methods:​

  • createInvoice(InvoiceRequest request)

    • Calculates subscription price and any linked VPS costs.
    • Generates the total amount and stores the invoice.
    • Invoice numbers are sequential and formatted as INV-{YEAR}-{COUNT}.

  • getInvoiceById(Long invoiceId) – Retrieve a specific invoice.

  • getAllInvoices() – Retrieve all invoices in the system.

  • getInvoicesBySubscriptionId(Long subscriptionId) – Retrieve invoices for a specific subscription.

  • deleteInvoice(Long invoiceId) – Delete an invoice.

  • generateInvoicePdf(Long invoiceId)

    • Generates a PDF representation of the invoice using Apache PDFBox.
    • Includes:
      • Invoice number
      • Issue date
      • Paid status
      • Subscription price
      • Total VPS price
      • Total amount
      • Subscription ID

  • getInvoicesForAuthenticatedUser()

    • Returns all invoices belonging to the authenticated user.

Workflow Examples​

Subscription Creation​

  1. User selects a plan.
  2. SubscriptionService.createSubscription validates the user and plan.
  3. Creates subscription entity with calculated end date and next billing date.
  4. Generates the first invoice via InvoiceService.

Plan Upgrade​

  1. User requests a plan change.
  2. changeUserSubscriptionPlan validates subscription status.
  3. Updates subscription with the new plan and recalculates price and end date.

Invoice Generation​

  1. Upon subscription creation or billing cycle renewal, InvoiceService.createInvoice calculates total cost.
  2. PDF generation is available via generateInvoicePdf.
  3. The invoice includes subscription and any associated VPS costs.

Notes​

  • Subscriptions are currently One-to-One with User. Future improvements may support multiple subscriptions per user.
  • Billing supports integration with VPS services to include hosting costs.
  • Invoice generation leverages PDFBox; can be extended to other PDF libraries or formats.
  • All operations are transactional to ensure data integrity.