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

# Subscriptions

> Multi-phase subscriptions with automatic invoice generation.

The subscription system enables flexible, time-based billing for customers with support for multi-phase pricing, recurring and one-time charges, prorated billing, and automatic invoice generation.

## Subscription model

Subscriptions are built on a hierarchical model:

```
Subscription
├── Subscription Phase (time-based period)
│   ├── Subscription Phase Item (product/pricing)
│   │   ├── Price reference
│   │   ├── Quantity setting
│   │   └── Price override (optional)
│   └── Subscription Phase Item
│       └── ...
└── Subscription Phase
    └── ...
```

### Subscriptions

The top-level container represents a customer's ongoing relationship with your service. Each subscription:

* Belongs to a specific customer and account
* Must have at least one subscription phase
* Derives its start and end dates from its phases
* Tracks billing cycles through phase transitions

### Subscription phases

Time-bounded periods within a subscription that define different billing terms:

* **Start date** -- when this phase begins
* **End date** -- when this phase ends (optional for the final phase)
* **Multiple items** -- each phase can contain multiple subscription items
* **Validation** -- phases cannot overlap and must be sequential

### Subscription phase items

Individual billable items within each phase:

* **Price reference** -- links to a specific product price
* **Quantity** -- how many units of this item (default: 1)
* **Price override** -- optional custom pricing that overrides the base price
* **Billing type** -- recurring or one-time charges
* **Validation** -- each phase must have at least one item, and all recurring items must share the same interval

## Key features

### Datetime precision

The subscription system uses full datetime fields (not just dates) for phase boundaries, enabling:

* **Hourly billing** -- cloud computing, parking, co-working spaces
* **Daily subscriptions** -- equipment rentals, temporary access
* **Precise transitions** -- exact moment when trials end and billing begins
* **No ambiguity** -- clear timezone-aware datetime boundaries

### Automatic validation

Built-in validations prevent billing errors:

* **No overlaps** -- phases cannot overlap in time
* **No gaps** -- phases must connect seamlessly (`end_date` = next `start_date`)
* **Sequential integrity** -- phases automatically validated for proper ordering
* **Interval consistency** -- all recurring items in a phase must have matching intervals
* **Price constraints** -- overrides must be non-negative (\$0 allowed for free trials)

### Billing cycle anchors

Billing cycle anchors control when recurring charges occur. See [Billing cycles](/guides/billing-cycles) for details.

## Creating a subscription

### Minimum requirements

To create a subscription, you need:

1. **Account** -- the business account that owns the subscription
2. **Customer** -- the customer receiving the subscription
3. **At least one phase** with a start date
4. **At least one phase item** linking to a price

### Basic subscription

```ruby theme={null}
# Simple monthly subscription
subscription = Subscription.new(
  account: account,
  customer: customer,
  billing_cycle_anchor: Time.zone.parse("2024-02-01"), # Optional
  proration_behavior: 'create_prorations' # Optional, defaults to 'create_prorations'
)

# Add a single phase
phase = subscription.subscription_phases.build(
  start_date: Time.current,
  end_date: nil # nil means ongoing/no end date
)

# Add items to the phase
phase.subscription_phase_items.build(
  price: monthly_price,
  quantity: 1
)

subscription.save!
```

### Multi-phase subscription

```ruby theme={null}
# Create a subscription with trial, promotional, and regular pricing phases
subscription = Subscription.new(
  account: account,
  customer: customer
)

# Phase 1: 14-day free trial
trial_start = Time.current
trial_end_date = trial_start + 14.days
trial_phase = subscription.subscription_phases.build(
  start_date: trial_start,
  end_date: trial_end_date
)
trial_phase.subscription_phase_items.build(
  price: monthly_plan_price,
  quantity: 1,
  overridden_price_amount: 0.00  # Free trial
)

# Phase 2: 3-month promotional pricing (starts when trial ends)
promo_end_date = trial_end_date + 3.months
promo_phase = subscription.subscription_phases.build(
  start_date: trial_end_date,
  end_date: promo_end_date
)
promo_phase.subscription_phase_items.build(
  price: monthly_plan_price,
  quantity: 1,
  overridden_price_amount: 19.99  # Discounted from regular $49.99
)

# Phase 3: Regular pricing (ongoing, starts when promo ends)
regular_phase = subscription.subscription_phases.build(
  start_date: promo_end_date,
  end_date: nil  # Ongoing
)
regular_phase.subscription_phase_items.build(
  price: monthly_plan_price,
  quantity: 1
  # No override - uses the price's standard amount
)

subscription.save!
```

## Validation rules

### Subscription level

* Must have at least one subscription phase
* Cannot exist without phases at any time

### Phase level

* Must have at least one subscription phase item
* Start date required on all phases
* End date required if subsequent phases exist
* Phases cannot overlap
* Phases must be sequential without gaps -- the `end_date` of one phase must exactly match the `start_date` of the next
* Supports hourly, daily, weekly, monthly, and yearly precision

### Phase item level

* Must reference a valid price
* Quantity must be a positive integer (minimum 1)
* Price overrides must be non-negative (can be \$0.00 for free trials)
* All recurring items in a phase must have the same interval type and count

## Sequential phases

When creating multi-phase subscriptions, phases must connect seamlessly:

```ruby theme={null}
# Correct: phases connect exactly
phase_1 = subscription.subscription_phases.build(
  start_date: Time.zone.parse("2024-01-01 00:00:00"),
  end_date: Time.zone.parse("2024-01-31 23:59:59")
)

phase_2 = subscription.subscription_phases.build(
  start_date: Time.zone.parse("2024-01-31 23:59:59"),
  end_date: Time.zone.parse("2024-02-29 23:59:59")
)
```

<Warning>
  Gaps between phases will fail validation. The `end_date` of one phase must exactly match the `start_date` of the next phase, down to the second.
</Warning>

### Hourly subscription example

```ruby theme={null}
# Co-working space with hourly billing
subscription = Subscription.new(account: account, customer: customer)

# Morning session: 9 AM - 1 PM
morning_phase = subscription.subscription_phases.build(
  start_date: Time.zone.parse("2024-01-15 09:00:00"),
  end_date: Time.zone.parse("2024-01-15 13:00:00")
)
morning_phase.subscription_phase_items.build(
  price: hourly_desk_price,  # $15/hour
  quantity: 4
)

# Afternoon session: 1 PM - 5 PM (connects seamlessly)
afternoon_phase = subscription.subscription_phases.build(
  start_date: Time.zone.parse("2024-01-15 13:00:00"),
  end_date: Time.zone.parse("2024-01-15 17:00:00")
)
afternoon_phase.subscription_phase_items.build(
  price: hourly_desk_price,
  quantity: 4
)

subscription.save!
```

## Interval consistency

All recurring items within a single subscription phase must have consistent billing intervals. This prevents ambiguity in invoice generation and billing calculations.

### Valid configurations

```ruby theme={null}
# All recurring items have the same interval (monthly, count 1)
phase.subscription_phase_items.build(price: monthly_plan_price, quantity: 1)      # month/1
phase.subscription_phase_items.build(price: monthly_addon_price, quantity: 2)     # month/1
phase.subscription_phase_items.build(price: one_time_setup_fee, quantity: 1)      # non-recurring (allowed)

# All recurring items have quarterly billing (monthly, count 3)
phase.subscription_phase_items.build(price: quarterly_base_price, quantity: 1)    # month/3
phase.subscription_phase_items.build(price: quarterly_support_price, quantity: 1) # month/3

# Different phases can have different intervals
phase_1.subscription_phase_items.build(price: monthly_price, quantity: 1)   # Phase 1: monthly
phase_2.subscription_phase_items.build(price: yearly_price, quantity: 1)    # Phase 2: yearly
```

### Invalid configurations

```ruby theme={null}
# Mixed interval types (monthly vs daily) -- will fail validation
phase.subscription_phase_items.build(price: monthly_price, quantity: 1)   # month/1
phase.subscription_phase_items.build(price: daily_price, quantity: 1)     # day/1

# Same interval type but different counts -- will fail validation
phase.subscription_phase_items.build(price: monthly_price, quantity: 1)     # month/1
phase.subscription_phase_items.build(price: quarterly_price, quantity: 1)   # month/3
```

<Note>
  Non-recurring items are exempt from interval consistency rules. One-time charges can coexist with any recurring interval type within the same phase.
</Note>

## Database structure

```sql theme={null}
subscriptions
├── customer_id (required)
├── account_id (required)
├── billing_cycle_anchor (datetime, optional)
├── proration_behavior (string, default: "create_prorations")
└── sandbox_id (optional)

subscription_phases
├── subscription_id (required)
├── start_date (datetime, required)
├── end_date (datetime, optional)
└── sandbox_id (optional)

subscription_phase_items
├── subscription_phase_id (required)
├── price_id (required)
├── quantity (integer, default: 1, must be >= 1)
├── overridden_price_amount (decimal, optional, must be >= 0)
└── sandbox_id (optional)
```

<Note>
  `start_date` and `end_date` are datetime fields (not date fields), enabling precise time-based billing for hourly and daily subscriptions.
</Note>

## Key methods

| Method                           | Description                                                       |
| -------------------------------- | ----------------------------------------------------------------- |
| `subscription.active_phase`      | Returns the current phase based on `Time.current`                 |
| `subscription.total_amount`      | Calculates the total recurring cost of the active phase           |
| `subscription.next_billing_date` | Determines when the next invoice should be generated              |
| `phase_item.effective_price`     | Returns `overridden_price_amount` or falls back to `price.amount` |
| `subscription.start_date`        | Returns the `start_date` of the first phase                       |
| `subscription.end_date`          | Returns the `end_date` of the active phase                        |

## Pricing flexibility

### Price overrides

Phase items can override the base price of a product:

* **Use case**: promotional pricing, volume discounts, custom contracts, free trials
* **Validation**: must be non-negative (>= 0), can be \$0.00 for free trials
* **Fallback**: uses the product's base price if no override is set (nil)

### Quantity support

Each phase item supports configurable quantities:

* **Use case**: per-seat licensing, usage-based billing, bulk purchases
* **Calculation**: `quantity x (overridden_price_amount || price.amount)`

### Billing intervals

Phase items inherit billing behavior from their associated prices:

* **Recurring**: monthly, weekly, yearly billing cycles
* **One-time**: charges that appear only once per phase

## Phase transitions

Subscriptions automatically transition between phases based on date ranges:

```
Phase 1: Trial Period (Day 1-30)
├── Basic Plan -- $0/month (overridden from $29/month)
└── Setup Fee -- $10 (one-time)

Phase 2: Discounted Period (Day 31-365)
├── Basic Plan -- $19/month (overridden from $29/month)
└── Premium Feature Add-on -- $5/month

Phase 3: Regular Pricing (Day 366+)
├── Basic Plan -- $29/month (standard pricing)
└── Premium Feature Add-on -- $5/month
```

At any given time, the subscription has one active phase -- the phase whose date range includes the current time. The active phase determines current billing amounts and drives invoice generation.

## Real-world scenarios

<AccordionGroup>
  <Accordion title="SaaS with trial, onboarding, and growth path">
    ```
    Phase 1 (Days 1-30): Free trial
    ├── Core Platform Access -- $0/month (overridden from $99)
    ├── Users Included -- 2 seats
    └── Support Level -- Basic (email only)

    Phase 2 (Days 31-120): Post-trial with onboarding
    ├── Core Platform Access -- $99/month
    ├── Users Included -- 5 seats
    ├── Onboarding Package -- $500 (one-time)
    ├── Dedicated Success Manager -- $0/month (included for first 3 months)
    └── Support Level -- Premium

    Phase 3 (Days 121-365): Growth phase
    ├── Core Platform Access -- $99/month
    ├── Additional User Seats -- $20/month x 5
    ├── API Access -- $49/month
    └── Support Level -- Premium

    Phase 4 (Day 366+): Enterprise
    ├── Core Platform Access -- $79/month (volume discount)
    ├── Unlimited Users -- $500/month (flat rate)
    ├── API Access -- $49/month
    ├── Custom Integrations -- $200/month
    └── Support Level -- Enterprise (24/7)
    ```
  </Accordion>

  <Accordion title="Education platform with semester-based billing">
    ```
    Phase 1: Fall Semester (Aug 15 - Dec 15)
    ├── Platform Access -- $49/month
    ├── Course Materials -- $100 (one-time)
    ├── Tutoring Hours -- 5 hours/month included
    └── Exam Proctoring -- $25 per exam (one-time)

    Phase 2: Winter Break (Dec 16 - Jan 14)
    ├── Platform Access -- $9.99/month (reduced rate)
    └── Study Materials Access -- Included

    Phase 3: Spring Semester (Jan 15 - May 15)
    ├── Platform Access -- $49/month
    ├── Course Materials -- $100 (one-time)
    ├── Tutoring Hours -- 5 hours/month included
    └── Exam Proctoring -- $25 per exam

    Phase 4: Summer Session (May 16 - Aug 14)
    ├── Platform Access -- $29/month (summer rate)
    ├── Course Materials -- $50 (reduced)
    └── Tutoring Hours -- 2 hours/month included
    ```
  </Accordion>

  <Accordion title="Fitness membership with commitment rewards">
    ```
    Phase 1 (Months 1-3): Explorer
    ├── Gym Access -- $79/month
    ├── Classes Included -- 4/month
    └── Personal Training Session -- $80 (one-time welcome session)

    Phase 2 (Months 4-6): Dedicated
    ├── Gym Access -- $69/month (reward for staying)
    ├── Classes Included -- 6/month
    └── Quarterly Fitness Assessment -- $0 (included)

    Phase 3 (Months 7-12): Champion
    ├── Gym Access -- $59/month
    ├── Classes Included -- 8/month
    ├── Guest Passes -- 2/month
    └── Quarterly Fitness Assessment -- $0 (included)

    Phase 4 (Month 13+): Elite
    ├── Gym Access -- $49/month (best rate)
    ├── Unlimited Classes -- Included
    ├── Guest Passes -- 4/month
    ├── Personal Training Session -- 1/quarter included
    └── Premium Locker -- Included
    ```
  </Accordion>

  <Accordion title="Professional services with project phases">
    ```
    Phase 1: Discovery and planning (Month 1)
    ├── Discovery Workshop -- $5,000 (one-time)
    ├── Stakeholder Interviews -- $2,000 (one-time)
    ├── Strategic Planning -- $150/hour x 40 hours
    └── Project Management -- $1,500/month

    Phase 2: Implementation (Months 2-4)
    ├── Development Work -- $175/hour x 160 hours/month
    ├── Weekly Progress Meetings -- Included
    ├── Project Management -- $2,500/month
    └── Cloud Infrastructure -- $500/month

    Phase 3: Launch and stabilization (Month 5)
    ├── Launch Support -- $10,000 (one-time)
    ├── On-call Support -- $200/hour (as needed)
    ├── Performance Optimization -- $5,000 (one-time)
    └── Training Sessions -- $1,000 per session x 4

    Phase 4: Maintenance and support (Month 6+)
    ├── Monthly Retainer -- $5,000/month (includes 20 hours)
    ├── Additional Hours -- $150/hour (beyond retainer)
    ├── Quarterly Reviews -- Included
    └── Priority Support SLA -- Included
    ```
  </Accordion>

  <Accordion title="Subscription box with introductory offer">
    ```
    Phase 1 (Months 1-3): New subscriber special
    ├── Monthly Box -- $9.99/month (overridden from $39.99)
    ├── Shipping -- FREE (overridden from $5.99)
    ├── Welcome Gift -- $20 value (one-time)
    └── Exclusive Member Forum -- Included

    Phase 2 (Months 4-12): Regular pricing with loyalty perks
    ├── Monthly Box -- $39.99/month
    ├── Shipping -- $5.99/month
    ├── Quarterly Bonus Item -- $15 value (every 3 months)
    └── Member Forum -- Included

    Phase 3 (Month 13+): VIP status
    ├── Monthly Box -- $39.99/month
    ├── Shipping -- FREE (reward for loyalty)
    ├── Quarterly Bonus Item -- $25 value
    ├── Early Access -- New products 48hrs early
    └── VIP Concierge Service -- Included
    ```
  </Accordion>

  <Accordion title="Enterprise software with usage-based scaling">
    ```
    Phase 1: Startup plan (0-10 employees)
    ├── Platform License -- $299/month
    ├── Users Included -- Up to 10
    ├── Data Storage -- 100GB included
    ├── API Calls -- 10,000/month included
    └── Support -- Business hours email

    Phase 2: Growth plan (11-50 employees)
    ├── Platform License -- $999/month
    ├── Users Included -- Up to 50
    ├── Data Storage -- 500GB included
    ├── API Calls -- 100,000/month included
    ├── Custom Integrations -- 2 included
    └── Support -- Priority phone and email

    Phase 3: Scale plan (51-200 employees)
    ├── Platform License -- $2,999/month
    ├── Users Included -- Up to 200
    ├── Data Storage -- 2TB included
    ├── API Calls -- 1,000,000/month included
    ├── Custom Integrations -- 5 included
    ├── Advanced Analytics -- Included
    └── Support -- 24/7 with 1-hour SLA

    Phase 4: Enterprise (201+ employees)
    ├── Platform License -- Custom negotiated base
    ├── Users -- Unlimited
    ├── Data Storage -- Unlimited
    ├── API Calls -- Unlimited
    ├── Custom Integrations -- Unlimited
    ├── Professional Services -- 40 hours/month included
    └── Support -- Dedicated team with 15-minute SLA
    ```
  </Accordion>
</AccordionGroup>

## Best practices

<Tip>
  Always use `Time.zone.parse()` or `Time.current` for phase boundaries, not `Date.parse()` or `Date.today`. Datetime precision prevents ambiguity in phase transitions.
</Tip>

1. **Sequential phases** -- ensure the `end_date` of one phase exactly matches the `start_date` of the next
2. **Clear transition points** -- define specific datetimes for phase transitions, considering time zones
3. **Consistent intervals** -- all recurring items within a phase must have the same interval type and count
4. **Value progression** -- each phase should provide clear value changes to justify pricing changes
5. **Test your phases** -- validate that phases connect properly and intervals are consistent before deploying to production
6. **Grace periods** -- consider buffer time between phases for major pricing increases (but ensure no gaps in datetime terms)
7. **Communication** -- notify customers before phase transitions that affect pricing
8. **Price override validation** -- price overrides can be \$0.00 (free trials) but not negative
9. **Last phase open-ended** -- the final phase can have `end_date: nil` for ongoing subscriptions

## Related pages

<CardGroup cols={2}>
  <Card title="Billing cycles" href="/guides/billing-cycles">
    Control when recurring charges occur with billing cycle anchors.
  </Card>

  <Card title="Invoice generation" href="/guides/invoice-generation">
    How invoices are automatically generated from subscriptions.
  </Card>
</CardGroup>