Subscriptions & Memberships

​

Overview

​

Subscription Types

​

Subscription Billing

​

Recurrence Options

• Monthly - Every 30 days
• Quarterly - Every 3 months
• Biannually - Every 6 months
• Yearly - Every 12 months
• Every Two Years - Every 24 months

​

Pricing per Recurrence

// Example pricing structure
Tier: "Premium"
  monthly: $10/month
  yearly: $100/year ($8.33/month, 17% savings)

​

Creating a Subscription Product

​

Basic Configuration

1. Enable Recurring Billing
   • Set is_recurring_billing flag
   • Choose default recurrence (monthly, yearly, etc.)
   • Enable is_tiered_membership for multiple tiers
2. Create Tiers
   • Add variant categories for membership levels
   • Name tiers (e.g., “Basic”, “Pro”, “Premium”)
   • Set prices for each recurrence period
   • Configure benefits and access levels
3. Content Delivery
   • Upload initial content for members
   • Set up drip content schedule
   • Configure workflows for automated delivery

​

Free Trials

# Enable free trial
product.update!(
  free_trial_enabled: true,
  free_trial_duration_amount: 1,
  free_trial_duration_unit: 'week' # or 'month'
)

1. Customer subscribes without being charged
2. Card is verified but not charged
3. Purchase state: not_charged with is_free_trial_purchase flag
4. After trial period, first charge processes
5. Subsequent charges continue on schedule

​

Subscription Lifecycle

​

Active Subscription States

​

Subscription Flow

​

Managing Subscriptions

​

Original Subscription Purchase

• Contains customer information
• Stores variant selection
• Holds offer code (if applicable)
• Used to generate recurring charges

# Recurring charge uses original purchase as template
new_purchase = subscription.build_purchase
  → Copies email, address, variants from original
  → Applies current pricing
  → Uses saved payment method

​

Charging Members

1. Scheduled - Worker scheduled for charge date
2. Build Purchase - Create new purchase from template
3. Process Payment - Charge saved payment method
4. Handle Result - Success or failure handling
5. Update Subscription - Track charge occurrence

​

Payment Failures

1. Immediate Retry - Retry after 1 hour if network error
2. Customer Email - “Your card was declined”
3. Grace Period - 5 days to update payment
4. Reminder Email - Sent 2 days before end
5. Auto-Cancel - If not resolved within 5 days

​

Subscription Upgrades & Downgrades

​

Changing Plans

subscription.update_current_plan!(
  new_variants: [new_tier_variant],
  new_price: new_tier_price,
  perceived_price_cents: customer_price
)

​

Proration Logic

• Charge difference immediately
• Prorate based on days remaining
• Next full charge on original schedule

• Apply at next billing date
• No immediate charge
• Customer keeps current tier until renewal

​

Plan Change Tracking

subscription.subscription_plan_changes.create!(
  from_variant: old_tier,
  to_variant: new_tier,
  applies_at: next_billing_date
)

​

Cancellation Management

​

Cancellation Types

1. By Customer - Self-service cancellation
2. By Seller - Admin cancellation
3. By System - Payment failure after grace period
4. Immediate - Chargeback or product deletion

​

Cancellation Workflow

# Standard cancellation (end of period)
subscription.cancel!(by_seller: false)
  → Sets cancelled_at to end of current period
  → Customer retains access until then
  → Sends cancellation confirmation email

# Immediate cancellation
subscription.cancel_effective_immediately!
  → Sets cancelled_at to now
  → Access revoked immediately
  → Used for chargebacks or deletions

​

Preventing Churn

• Offer discount when member cancels
• One-time offer code applied
• Reduces price for next few months

offer_code = product.cancellation_discount_offer_code
# Presented at cancellation flow

​

Access After Cancellation

• block_access_after_membership_cancellation - Remove access immediately
• Default behavior - Keep access until period end

​

Member Management

​

Member Dashboard

• View current plan and billing
• Update payment method
• Change membership tier
• Cancel subscription
• Access member content

​

Authentication

1. Cookie Authentication - Set after purchase
2. User Login - If member has Gumroad account
3. Magic Link - Email a one-time access token

# Magic link generation
subscription.update!(
  token: SecureRandom.hex,
  token_expires_at: 24.hours.from_now
)

​

Member Communication

• Subscription confirmation
• Payment receipt (each charge)
• Payment failure notice
• Cancellation confirmation
• Renewal reminders (optional)

• Broadcast emails to all members
• Tier-specific announcements
• Product update notifications

​

Content Delivery

​

Initial Access

1. Existing installments/posts delivered
2. Access to member-only content
3. Integration activations (Discord, etc.)

​

Ongoing Delivery

​

Installments

installment.create!(
  title: "Week 3: Advanced Techniques",
  content: "...",
  published_at: 3.weeks.from_now
)

• Members see all past installments
• New installments appear on publish date
• should_include_last_post - Show most recent before subscribe
• should_show_all_posts - Show all posts (for tiered memberships)

​

Payment Methods

​

Supported Payment Options

• Credit/Debit Cards - Stored via Stripe
• PayPal Billing Agreements - Recurring PayPal
• Apple Pay / Google Pay - Mobile payments

​

Payment Method Updates

subscription.update_payment_method!(
  payment_option: new_card,
  credit_card_id: new_card.id
)

​

Card Updates

• Stripe automatic card updates
• Email reminder before card expires
• Self-service card replacement

​

Subscription Analytics

​

Key Metrics

​

Cohort Analysis

# Subscriptions by month
subscriptions.group_by { _1.created_at.beginning_of_month }

# Retention over time
subscription.alive_at?(6.months.ago) # Was active 6 months ago?

​

Subscription Events

• Created
• Charge succeeded
• Charge failed
• Restarted (after failure)
• Deactivated (ended/cancelled)

​

Advanced Features

​

Installment Plans

product.create_installment_plan!(
  number_of_charges: 3,
  recurrence: :monthly
)

• Immediate access after first payment
• Subsequent charges automatic
• Member retains access if paid
• Cannot be cancelled by buyer

​

Gifted Subscriptions

1. Gifter completes purchase
2. Giftee receives notification
3. Giftee can manage subscription
4. Renewal charges gifter or giftee’s card

​

Quantity-Based Pricing

subscription.update!(
  quantity: 5 # 5 seats
)
# Charged: base_price * quantity

​

Fixed-Length Subscriptions

subscription.update!(
  fixed_length: true,
  total_charges: 12 # 1 year if monthly
)

• Ends automatically after final charge
• Sends completion notification
• No renewal or cancellation needed

​

Subscription Workflows

​

Automated Actions

• Send welcome email sequence
• Add to Discord server
• Grant community access
• Deliver bonus content

• Send feedback survey
• Offer win-back discount
• Remove integrations
• Schedule follow-up

• Thank you message
• Unlock new content
• Reward loyalty perks

​

API and Webhooks

​

Subscription API

// Get subscriber list
GET /v2/products/:id/subscribers

// Get specific subscription
GET /v2/subscribers/:id

// Cancel subscription
DELETE /v2/subscribers/:id

​

Webhook Events

// Subscription created
{
  "subscription": {
    "id": "sub_123",
    "product_id": "prod_abc",
    "email": "[email protected]",
    "recurrence": "monthly",
    "status": "active"
  }
}

// Subscription cancelled
{
  "subscription": {
    "id": "sub_123",
    "cancelled_at": "2024-01-31T23:59:59Z",
    "status": "cancelled"
  }
}

​

Best Practices

​

Troubleshooting

​

Common Issues

• Expired cards
• Insufficient funds
• Bank fraud blocks
• Incorrect billing address

• Unclear value proposition
• Inconsistent content delivery
• Poor onboarding
• Pricing too high

​

Next Steps