Subscriptions

Subscriptions represent ongoing recurring billing relationships with customers. RevKeen automatically generates invoices, processes payments, and handles the complete subscription lifecycle.

Subscription Lifecycle

┌─────────┐     ┌──────────┐     ┌────────┐
│ PENDING │────▶│ TRIALING │────▶│ ACTIVE │
└─────────┘     └──────────┘     └───┬────┘
                                     │
                    ┌────────────────┼────────────────┐
                    │                │                │
                    ▼                ▼                ▼
              ┌──────────┐    ┌──────────┐    ┌──────────┐
              │ PAST_DUE │    │  PAUSED  │    │ CANCELED │
              └────┬─────┘    └──────────┘    └──────────┘
                   │
                   ▼
              ┌──────────┐
              │  UNPAID  │
              └──────────┘

Subscription Statuses

Subscription Items

A subscription can contain multiple items, similar to Stripe's model. This allows you to bundle multiple products in a single subscription.

// Subscription with multiple items
const subscription = await client.subscriptions.create({
  customerId: 'cus_xxxxxxxx',
  items: [
    {
      priceId: 'price_pro_monthly',  // Pro plan at $49/mo
      quantity: 1,
    },
    {
      priceId: 'price_extra_users',  // Extra users at $10/mo each
      quantity: 5,
    },
  ],
});

// Each item generates its own line on invoices

Creating Subscriptions

Via Checkout

The most common way to create subscriptions is through checkout links:

1. Create a checkout link with a recurring price
2. Customer completes checkout
3. Subscription is automatically created
4. First invoice is generated and charged

Via API

const subscription = await client.subscriptions.create({
  customerId: 'cus_xxxxxxxx',

  items: [
    {
      priceId: 'price_xxxxxxxx',
      quantity: 1,
    },
  ],

  // Optional: Start with a trial
  trialPeriodDays: 14,

  // Optional: Custom billing anchor
  billingCycleAnchor: new Date('2025-02-01'),

  // Optional: Default payment method
  defaultPaymentMethodId: 'pm_xxxxxxxx',
});

console.log(subscription.data.status); // 'trialing' or 'active'

Trial Periods

Trials allow customers to try your product before paying:

• Subscription status is trialing
• Customer has full access during the trial
• No payment is collected
• At trial end, first invoice is created and charged
• If payment fails, subscription enters past_due

Billing Cycle

Each subscription has a billing cycle that determines when invoices are generated:

Managing Subscriptions

Pause a Subscription

await client.subscriptions.pause('sub_xxxxxxxx', {
  // Optional: Auto-resume after a period
  resumeAt: new Date('2025-03-01'),
});

Resume a Subscription

await client.subscriptions.resume('sub_xxxxxxxx');

Cancel a Subscription

// Cancel immediately
await client.subscriptions.cancel('sub_xxxxxxxx');

// Cancel at end of current period
await client.subscriptions.cancel('sub_xxxxxxxx', {
  cancelAtPeriodEnd: true,
});

Dunning (Payment Recovery)

When a subscription payment fails, RevKeen automatically enters the dunning process:

1. Subscription status changes to past_due
2. Payment is retried according to your retry schedule
3. Customer receives reminder emails
4. If all retries fail, subscription becomes unpaid or canceled

Subscription Events

Related