> ## Documentation Index
> Fetch the complete documentation index at: https://altostrat.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Subscription Management & Invoicing: Resource Pooling, Billing Cycles & Payment Processing

> Complete guide to workspace subscription management including resource pooling, trial subscriptions, payment methods, invoicing, and usage metering. Learn billing account limits and subscription lifecycle management.

## What is Subscription Management?

Subscription management defines the resources available to your workspace and how billing is processed. This comprehensive system handles resource allocation, payment processing, usage metering, and invoice generation through integrated Stripe billing.

**Key subscription capabilities:**

* Resource pooling across multiple subscriptions
* Automated billing cycles and invoice generation
* Trial subscription management
* Usage metering and limit enforcement
* Multi-payment method support

## How Subscriptions Work with Billing Accounts

Subscriptions connect billing accounts to resource allocation, providing specific quantities of products (users, locations, SSO connections) that organizations can consume. Each subscription generates automated invoices processed through Stripe integration.

**Subscription architecture:**

* Each subscription belongs to a specific billing account
* Subscriptions provide defined quantities of products/resources
* Multiple subscriptions per billing account enable resource pooling
* Automated invoice generation and payment processing

```mermaid theme={null}
graph LR
    BA[Billing Account] --> S1[Subscription 1]
    BA --> S2[Subscription 2]
    S1 --> P1[Product: Users<br/>Quantity: 50]
    S1 --> P2[Product: SSO<br/>Quantity: 1]
    S2 --> P3[Product: Users<br/>Quantity: 30]
    S2 --> P4[Product: Locations<br/>Quantity: 5]
    
    subgraph "Pooled Resources in Billing Account"
        PR[Total Users: 80<br/>Total SSO: 1<br/>Total Locations: 5]
    end
    
    P1 & P3 -- contributes to --> PR
    P2 -- contributes to --> PR
    P4 -- contributes to --> PR
```

## Resource Pooling: Subscription Aggregation in Billing Accounts

Resource pooling automatically combines product quantities from multiple subscriptions within a billing account, creating larger, more flexible resource pools for dynamic allocation.

**How resource pooling works:**

* Multiple subscriptions within a billing account automatically pool resources
* Different product types combine separately (users + users, locations + locations)
* Organizations draw from the combined resource pool
* Enables flexible allocation beyond individual subscription limits

### Resource Pool Access and Allocation

Organizations access pooled resources based on billing account relationships and workspace billing mode configuration:

```mermaid theme={null}
graph TD
    subgraph "Billing Account: ACME Corp"
        S1["Subscription 1<br/>(Marketing Dept)<br/>20 Users"]
        S2["Subscription 2<br/>(Sales Dept)<br/>30 Users"]
        S3["Subscription 3<br/>(Engineering Dept)<br/>50 Users"]
        
        subgraph "Available Resource Pool"
            Pool["Total Capacity: 100 Users"]
        end
        
        S1 --> Pool
        S2 --> Pool
        S3 --> Pool
    end
    
    O1[Marketing Org<br/>Using: 25 users]
    O2[Sales Org<br/>Using: 40 users]
    O3[Engineering Org<br/>Using: 35 users]
    
    Pool -.-> O1 & O2 & O3
```

### Resource Pooling Benefits

1. **Dynamic allocation**: Organizations can exceed individual subscription limits as long as total usage stays within pooled capacity
2. **Financial flexibility**: Separate invoicing for each subscription enables clear budget tracking and departmental billing
3. **Scalable capacity**: Add temporary subscriptions for seasonal demands without modifying base subscription structure
4. **Cost optimization**: Maximize resource utilization across organizational units

### Subscription Limits and Workarounds

**Important**: Each billing account supports maximum **3 active subscriptions**. For customers requiring additional distinct invoices, create multiple billing accounts to exceed this limit.

## Trial Subscriptions: Free 14-Day Platform Access

New workspaces automatically qualify for comprehensive 14-day trials providing full platform access without upfront payment requirements, enabling complete evaluation of workspace capabilities.

### Trial Eligibility Requirements

Workspace trial eligibility follows strict criteria to ensure fair access:

**Automatic trial qualification requires:**

* ✅ Exactly one billing account in the workspace
* ✅ No prior or existing subscriptions on that billing account

**Trial disqualification occurs when:**

* Multiple billing accounts exist in workspace
* Any subscription has been previously activated
* Trial period has been previously utilized

```mermaid theme={null}
graph LR
    NW[New Workspace] --> BA[Create Single Billing Account]
    BA -- No subscriptions? --> TRIAL[Activate 14-Day Trial]
    TRIAL --> CONVERT{Day 14}
    CONVERT -->|Payment Method Added| PAID[Convert to Paid Subscription]
    CONVERT -->|No Payment Method| SUSPEND[Access Suspended]
```

### Trial Conversion: Seamless Transition to Paid Service

Ensure uninterrupted service by adding payment methods before trial expiration. The system automatically handles conversion to paid subscriptions with immediate invoice generation.

**Conversion process:**

1. Add default payment method before trial expiration
2. System automatically converts trial to paid subscription
3. First invoice generated immediately upon conversion
4. Uninterrupted access to all workspace features

## Advanced Subscription Management

Comprehensive subscription management capabilities for dynamic resource allocation and billing optimization:

### How to Modify Active Subscriptions

Dynamic subscription modification supports real-time business needs while protecting against service disruption:

**Available modifications:**

* Adjust product quantities (increase or decrease)
* Add or remove products from existing subscriptions
* Change billing cycle frequency (monthly/annual)
* Modify subscription pricing tiers

**Protection mechanisms:**

* Prevent capacity reduction below current usage levels
* Validate changes against organizational limits
* Ensure service continuity during modifications

```mermaid theme={null}
graph TD
    CURRENT[Current Subscription<br/>50 Users, Monthly]
    MODIFY{Modification Request}
    
    subgraph "Possible Changes"
        UP[Upgrade to 100 Users]
        DOWN[Downgrade to 25 Users]
        ADD[Add 10 Locations]
    end
    
    CURRENT --> MODIFY
    MODIFY --> UP & DOWN & ADD
    
    UP --> IMMEDIATE[Change takes effect immediately.<br>Prorated charge on next invoice.]
    DOWN --> NEXT_CYCLE[Change takes effect at the start of the next billing cycle.]
    ADD --> IMMEDIATE
```

### Subscription Lifecycle

The status of a subscription changes based on user actions and payment events.

```mermaid theme={null}
stateDiagram-v2
    [*] --> Trialing: New eligible workspace
    [*] --> Active: Direct purchase with payment method
    Trialing --> Active: Payment method added
    Active --> Canceled: User cancels
    Active --> Past_Due: Payment fails
    Past_Due --> Active: Payment succeeds
    Past_Due --> Unpaid: Grace period ends
    Unpaid --> Canceled: Deemed uncollectible
    Canceled --> [*]: Subscription terminated
```

## Invoice Management: Automated Billing and Payment Processing

Comprehensive invoice management through Stripe integration provides automated billing cycles, payment processing, and detailed financial reporting.

### Invoice Structure and Components

Detailed invoice breakdowns provide complete transparency for financial tracking and accounting:

**Standard invoice elements:**

* Subscription line items with product quantities and rates
* Tax calculations based on billing address and regulations
* Applied discounts, credits, and promotional adjustments
* Clear subtotals and final amount due

```mermaid theme={null}
graph TD
    INV[Invoice #1234]
    
    subgraph "Line Items"
        L1[Subscription: User Licenses<br/>50 × $10 = $500]
        L2[Subscription: Locations<br/>5 × $50 = $250]
        L3[Credit: Promotional<br/>-$50]
    end
    
    subgraph "Summary"
        SUB[Subtotal: $700]
        TAX[Tax: $70]
        TOT[Total Due: $770]
    end
    
    INV --> L1 & L2 & L3
    L1 & L2 & L3 --> SUB
    SUB --> TAX
    TAX --> TOT
```

### Invoice Preview: Understand Financial Impact Before Changes

Preview upcoming invoices before finalizing subscription modifications to understand complete financial impact including prorated charges and adjustments.

**Preview capabilities:**

* View financial impact of quantity changes
* Calculate prorated charges for mid-cycle modifications
* Understand tax implications of subscription changes
* Preview total cost before confirming modifications

## Payment Method Management: Secure Multi-Method Support

Comprehensive payment method management with secure storage and automated failover capabilities through Stripe integration.

**Payment method capabilities:**

* Store up to 5 payment methods per billing account
* Secure tokenization and PCI compliance through Stripe
* Automated payment method failover and retry logic
* Support for multiple payment types (cards, bank transfers)

```mermaid theme={null}
graph LR
    BA[Billing Account]
    PM1[💳 Visa ****1234<br/>Default]
    PM2[💳 Amex ****5678<br/>Backup]
    PM3[🏦 Bank ****9012<br/>For Large Invoices]
    
    BA --> PM1
    BA --> PM2
    BA --> PM3
```

### Payment Method Hierarchy and Failover

* **Primary payment method**: Default method charged for all invoices and subscriptions
* **Backup payment methods**: Automatic failover when primary method fails
* **Intelligent retry logic**: Systematic retry across available payment methods
* **Proactive notifications**: Automated alerts for payment failures and card expirations

## Usage Metering: Resource Consumption Tracking and Enforcement

Sophisticated usage metering system tracks resource consumption against subscription limits with real-time enforcement and accurate billing protection.

**Usage metering features:**

* Real-time resource consumption tracking
* Automatic limit enforcement across organization hierarchies
* Subscription-based metering (not pay-as-you-go)
* Comprehensive usage reporting and analytics

### Usage Tracking Process and Validation

Usage tracking employs sophisticated validation against organizational limits and subscription pools with real-time enforcement:

**Tracking workflow:**

1. Product services report usage to workspace API
2. System validates against effective organizational limits
3. Subscription pool capacity checked in real-time
4. Usage accepted or rejected based on available capacity
5. Atomic updates ensure data consistency and accuracy

```mermaid theme={null}
sequenceDiagram
    participant Product Microservice
    participant Workspace API
    participant Stripe & DynamoDB
    
    Product Microservice->>+Workspace API: Report Usage (+1 User for Org X)
    Workspace API->>+Stripe & DynamoDB: Lock resource pool for Org X
    Workspace API->>Workspace API: Check current usage vs. limits
    alt Usage is within limits
        Workspace API->>+Stripe & DynamoDB: Atomically increment usage counter
        Stripe & DynamoDB-->>-Workspace API: Success
        Workspace API-->>-Product Microservice: OK (202)
    else Usage exceeds limits
        Workspace API-->>Product Microservice: Limit Exceeded (422)
    end
    Stripe & DynamoDB-->>-Workspace API: Release lock
```

### Usage Metering Reliability and Accuracy

Enterprise-grade usage metering with comprehensive protection against billing errors and resource over-consumption:

**Reliability mechanisms:**

* **Race condition prevention**: Distributed locking ensures sequential processing of concurrent usage reports
* **Idempotent operations**: Duplicate usage reports automatically detected and prevented
* **Hierarchical validation**: Most restrictive limits enforced across organization and subscription boundaries
* **Atomic transactions**: Database operations ensure complete consistency and accuracy