Overview

The Billing Service is responsible for managing all billing-related operations for subscriptions. It is part of the Subscriptions Subscriptions Domain v0.0.1 Manages subscription lifecycle, billing cycles, and plan management for recurring revenue streams. Owner subscriptions-management Map View docs domain and works with the BillingProfile BillingProfile Entity v1.0.0 Stores billing-related contact information and preferences for a customer, often used for invoices and communication. View docs entity.

The service receives Payment Processed Payment Processed Event v1.0.0 Event is triggered after the payment has been successfully processed Owner dboyne Schema Map View docs and publishes Invoice Generated Invoice Generated Event v0.0.1 Emitted when an invoice is generated for a subscription Schema Map View docs and Subscription Payment Due Subscription Payment Due Event v0.0.1 Emitted when a subscription payment is due for collection Schema Map View docs events. It coordinates with the Payment Service Payment Service Service v0.0.1 Service that handles payments Publishes PaymentProcessed Subscribes PaymentInitiated Owner dboyne Map Repo View docs to ensure timely payment collection and participates in the Subscription Renewal Flow Subscription Renewal Flow Flow v1.0.0 Business flow for automatic subscription renewals and related processes Owner subscriptions-management View flow View docs and User Cancels Subscription User Cancels Subscription Flow v1.0.0 Flow for when a user has cancelled a subscription Owner subscriptions-management View flow View docs flows.

Key Features

• Billing Cycle Management: Handles daily, weekly, monthly, quarterly, and annual billing cycles
• Invoice Generation: Creates detailed invoices with line items and tax calculations
• Payment Scheduling: Schedules recurring payments based on billing cycles
• Proration: Calculates prorated charges for mid-cycle changes
• Dunning Management: Handles failed payment retry logic

API Endpoints

REST API

• GET /api/billing/invoice/{subscriptionId} - Get current invoice
• GET /api/billing/history/{subscriptionId} - Get billing history
• POST /api/billing/preview - Preview upcoming charges
• PUT /api/billing/retry/{invoiceId} - Retry failed payment

Billing Cycle States

Configuration

billing_service:
  cycles:
    - daily
    - weekly
    - monthly
    - quarterly
    - annual
  retry_attempts: 3
  retry_interval_days: [1, 3, 7]
  invoice_generation_lead_days: 7