Subscriptions

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 for details.

Creating a subscription

Minimum requirements

To create a subscription, you need:

Account — the business account that owns the subscription
Customer — the customer receiving the subscription
At least one phase with a start date
At least one phase item linking to a price

Basic subscription

# 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

# 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:

# 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")
)

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.

Hourly subscription example

# 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

# 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

# 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

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

Database structure

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)

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

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

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)

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

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

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

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

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

Best practices

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

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

Billing cycles

Control when recurring charges occur with billing cycle anchors.

Invoice generation

How invoices are automatically generated from subscriptions.

Get started

Payments

Billing

Developers

Subscriptions

Subscription model

Subscriptions

Subscription phases

Subscription phase items

Key features

Datetime precision

Automatic validation

Billing cycle anchors

Creating a subscription

Minimum requirements

Basic subscription

Multi-phase subscription

Validation rules

Subscription level

Phase level

Phase item level

Sequential phases

Hourly subscription example

Interval consistency

Valid configurations

Invalid configurations

Database structure

Key methods

Pricing flexibility

Price overrides

Quantity support

Billing intervals

Phase transitions

Real-world scenarios

Best practices

Billing cycles

Invoice generation

​Subscription model

​Subscriptions

​Subscription phases

​Subscription phase items

​Key features

​Datetime precision

​Automatic validation

​Billing cycle anchors

​Creating a subscription

​Minimum requirements

​Basic subscription

​Multi-phase subscription

​Validation rules

​Subscription level

​Phase level

​Phase item level

​Sequential phases

​Hourly subscription example

​Interval consistency

​Valid configurations

​Invalid configurations

​Database structure

​Key methods

​Pricing flexibility

​Price overrides

​Quantity support

​Billing intervals

​Phase transitions

​Real-world scenarios

​Best practices

​Related pages

Billing cycles

Invoice generation

Subscription model

Subscriptions

Subscription phases

Subscription phase items

Key features

Datetime precision

Automatic validation

Billing cycle anchors

Creating a subscription

Minimum requirements

Basic subscription

Multi-phase subscription

Validation rules

Subscription level

Phase level

Phase item level

Sequential phases

Hourly subscription example

Interval consistency

Valid configurations

Invalid configurations

Database structure

Key methods

Pricing flexibility

Price overrides

Quantity support

Billing intervals

Phase transitions

Real-world scenarios

Best practices

Related pages