💳 Store & Subscription Processing

📖 Overview

The Store module handles all subscription lifecycle operations including downgrades, cancellations, activations, billing charges, and invoice processing.

Environment Flags:

• QM_SUBSCRIPTION_DOWNGRADE=true - Subscription downgrade processing
• QM_SUBSCRIPTION_CANCEL=true - Subscription cancellation processing
• QM_SUBSCRIPTION_ACTIVATE=true - Subscription activation processing
• QM_SUBSCRIPTION_PENDING_SUBACCOUNT_CHARGE=true - Subaccount billing
• QM_SUBSCRIPTION_CHARGE_MAINACCOUNT=true - Main account charges
• QM_DRAFT_INVOICE=true - Draft invoice status updates

Source Location: queue-manager/crons/store/

Processing Pattern: High-frequency polling (every 30 seconds) + Daily processing

🗄️ Collections Used

billing-subscription

• Operations: Read/Write
• Model: shared/models/billing-subscription.js
• Usage: Track subscription status and changes

billing-charge

• Operations: Create/Update
• Model: shared/models/billing-charge.js
• Usage: Record billing transactions

billing-customer

• Operations: Read/Write
• Model: shared/models/billing-customer.js
• Usage: Customer billing information

accounts

• Operations: Read/Write
• Model: shared/models/account.js
• Usage: Account subscription status updates

🔄 Processing Flow

graph TB
    DOWNGRADE[Downgrade Cron<br/>Every 30s]
    CANCEL[Cancel Cron<br/>Every 30s]
    ACTIVATE[Activate Cron<br/>Every 30s]
    CHARGE_SUB[Subaccount Charge<br/>Daily]
    CHARGE_MAIN[Main Charge<br/>Daily]
    INVOICE[Draft Invoice<br/>Hourly]

    DOWNGRADE -->|Query| SUB[(billing-subscription)]
    CANCEL -->|Query| SUB
    ACTIVATE -->|Query| SUB

    DOWNGRADE -->|Update| ACC[(accounts)]
    CANCEL -->|Update| ACC
    ACTIVATE -->|Update| ACC

    CHARGE_SUB -->|Create| CHARGE[(billing-charge)]
    CHARGE_MAIN -->|Create| CHARGE

    INVOICE -->|Update via Stripe| SUB

🔧 Jobs in This Module

Subscription Lifecycle

• 📘 Downgrade - Process subscription tier downgrades
• 📗 Cancel - Handle subscription cancellations
• 📙 Activate - Activate pending subscriptions

Billing & Charges

• 📕 Pending Subaccount Charge - Process subaccount billing
• 📓 Charge Main Account - Main account billing processing
• 📔 Draft Invoices - Stripe invoice status synchronization

⚙️ Configuration

Required Environment Variables:

# Subscription Management
QM_SUBSCRIPTION_DOWNGRADE=true
QM_SUBSCRIPTION_CANCEL=true
QM_SUBSCRIPTION_ACTIVATE=true

# Billing
QM_SUBSCRIPTION_PENDING_SUBACCOUNT_CHARGE=true
QM_SUBSCRIPTION_CHARGE_MAINACCOUNT=true
QM_DRAFT_INVOICE=true

# Dependencies
MONGO_DB_URL=...
STRIPE_SECRET_KEY=...        # Stripe API integration

---

📘 Downgrade Processing

Overview

Processes subscription tier downgrades scheduled for execution.

Cron Schedule: */30 * * * * * (Every 30 seconds)

Source Files:

• Cron: queue-manager/crons/store/subscriptions/downgrade.js
• Service: queue-manager/services/store/subscriptions/downgrade.js

Key Features

• Scheduled Downgrades: Processes at end of billing period
• Feature Access: Updates account feature limits
• Prorated Credits: Applies credits for unused time
• Notification: Triggers downgrade confirmation emails
• Rollback Support: Error handling with transaction support

---

📗 Cancel Processing

Overview

Handles subscription cancellation requests and cleanup.

Cron Schedule: */30 * * * * * (Every 30 seconds)

Source Files:

• Cron: queue-manager/crons/store/subscriptions/cancel.js
• Service: queue-manager/services/store/subscriptions/cancel.js

Key Features

• Immediate/Scheduled: Support for immediate or end-of-period cancellation
• Stripe Integration: Cancels Stripe subscriptions
• Access Revocation: Removes feature access
• Data Retention: Preserves data per retention policy
• Cancellation Surveys: Triggers feedback collection

---

📙 Activate Processing

Overview

Activates pending subscriptions after successful payment.

Cron Schedule: */30 * * * * * (Every 30 seconds)

Source Files:

• Cron: queue-manager/crons/store/subscriptions/activate.js
• Service: queue-manager/services/store/subscriptions/activate.js

Key Features

• Payment Verification: Confirms payment before activation
• Feature Provisioning: Enables all subscription features
• Welcome Flow: Triggers onboarding emails
• Trial Handling: Manages trial period activations

---

📕 Pending Subaccount Charge

Overview

Processes billing for subaccounts under main account.

Cron Schedule: Daily

Source Files:

• Cron: queue-manager/crons/store/invoices/pending_subaccount_charge.js
• Service: queue-manager/services/store/invoices/pending_subaccount_charge.js

Key Features

• Consolidated Billing: Charges main account for subaccounts
• Usage Tracking: Calculates per-subaccount usage
• Invoice Generation: Creates detailed invoices

---

📓 Charge Main Account

Overview

Processes primary billing charges for main accounts.

Cron Schedule: Daily

Source Files:

• Cron: queue-manager/crons/store/charge/charge_mainaccount.js
• Service: queue-manager/services/store/charge/charge_mainaccount.js

Key Features

• Recurring Charges: Monthly/annual billing
• Payment Processing: Stripe charge creation
• Failed Payment Handling: Retry logic and notifications

---

📔 Draft Invoice Processing

Overview

Synchronizes draft invoice status with Stripe.

Cron Schedule: Hourly

Source Files:

• Cron: queue-manager/crons/store/draftInvoices.js
• Service: queue-manager/services/store/draftInvoices.js

Key Features

• Status Sync: Updates invoice status from Stripe
• Payment Confirmation: Marks invoices as paid
• Failed Payment Tracking: Identifies payment failures

---

🔗 Related Documentation

• Queue Manager Overview
• Architecture (documentation unavailable)
• Configuration

---

Module Status: Active
Execution Pattern: High-frequency polling + Daily/Hourly
Last Updated: 2025-10-10