Manage Money

Subscriptions

Charge customers automatically every week, month, or year. Perfect for memberships, SaaS, streaming, and any recurring service.

8 min read

What are Subscriptions?

A subscription charges a customer on a regular schedule - like $10 every month or $99 every year. You set it up once, and ClapPay handles the billing automatically.

When a subscription renews, ClapPay creates an invoice, charges the customer's saved payment method, and sends you a webhook so you know it worked.

Key Concepts

Products

What you're selling. For example, "Premium Plan" or "Monthly Box". Products can have multiple prices.

Prices

How much and how often to charge. One product might have a $10/month price and a $100/year price.

Customers

People who pay you. Each customer can have saved payment methods and multiple subscriptions.

Invoices

ClapPay creates an invoice each billing period. You can customize what appears on invoices.

Create a Subscription

Step 1: Create a Product and Price

First, set up what you're selling:

const clappay = require('@clappay/sdk')('sk_live_...');

// Create a product
const product = await clappay.products.create({
  name: 'Premium Plan',
  description: 'Access to all premium features',
});

// Create a monthly price
const price = await clappay.prices.create({
  product: product.id,
  unit_amount: 1999,  // $19.99
  currency: 'usd',
  recurring: {
    interval: 'month',  // 'day', 'week', 'month', or 'year'
  },
});

console.log('Price ID:', price.id);  // Save this!

You can also create products and prices in the Dashboard under Products.

Step 2: Create a Customer

Next, create a customer to subscribe:

// Create a customer
const customer = await clappay.customers.create({
  email: 'customer@example.com',
  name: 'Jane Smith',
});

// Save payment method to the customer
// (Use your frontend to collect payment details first)

Step 3: Start the Subscription

Now create the subscription:

const subscription = await clappay.subscriptions.create({
  customer: customer.id,
  items: [
    { price: 'price_abc123...' },  // Your price ID
  ],
  payment_behavior: 'default_incomplete',
  expand: ['latest_invoice.payment_intent'],
});

// Check if first payment succeeded
if (subscription.status === 'active') {
  console.log('Subscription started!');
} else {
  // Customer needs to complete payment
  console.log('Send customer to complete payment');
}

Subscription Status

Status	What It Means
trialing	Free trial period (no charge yet)
active	Everything is good, customer is paying
past_due	Payment failed, retrying automatically
unpaid	All retries failed
canceled	Subscription was canceled
incomplete	Waiting for first payment

Free Trials

Give customers a chance to try before they buy:

const subscription = await clappay.subscriptions.create({
  customer: customer.id,
  items: [{ price: 'price_abc123...' }],
  trial_period_days: 14,  // 14-day free trial
});

// Customer won't be charged until trial ends

You can still collect payment details upfront. When the trial ends, ClapPay automatically charges the saved payment method.

Change Plans (Upgrade/Downgrade)

When a customer wants to switch plans:

// Get the subscription item ID first
const subscription = await clappay.subscriptions.retrieve('sub_abc123...');
const itemId = subscription.items.data[0].id;

// Change to a new price
await clappay.subscriptions.update('sub_abc123...', {
  items: [{
    id: itemId,
    price: 'price_new_plan...',  // New price ID
  }],
  proration_behavior: 'create_prorations',  // Credit for unused time
});

Proration means ClapPay calculates the difference. If a customer upgrades mid-month, they pay only for the remaining days at the higher price.

Cancel Subscriptions

You can cancel immediately or at the end of the billing period:

Cancel at end of period (recommended)

// Customer keeps access until their paid period ends
await clappay.subscriptions.update('sub_abc123...', {
  cancel_at_period_end: true,
});

// subscription.cancel_at shows when it will end

Cancel immediately

// Ends subscription right now
await clappay.subscriptions.cancel('sub_abc123...');

Handle Failed Payments

Sometimes payments fail - expired cards, insufficient funds, etc. ClapPay automatically retries failed payments with Smart Retry:

First retry: Next day
Second retry: 3 days later
Third retry: 5 days later
Final retry: 7 days later

Set up webhooks to know when payments fail so you can:

Email the customer to update their card
Show a banner in your app asking them to fix payment
Limit access to paid features

// Listen for payment failures
app.post('/webhooks/clappay', async (req, res) => {
  const event = req.body;
  
  if (event.type === 'invoice.payment_failed') {
    const invoice = event.data.object;
    const customerId = invoice.customer;
    
    // Send email to customer
    await sendPaymentFailedEmail(customerId);
  }
  
  res.status(200).send('OK');
});

Important Webhooks

Event	When It Happens
customer.subscription.created	New subscription started
customer.subscription.updated	Subscription changed (plan, status, etc.)
customer.subscription.deleted	Subscription ended
invoice.paid	Monthly/yearly payment succeeded
invoice.payment_failed	Payment attempt failed
customer.subscription.trial_will_end	Trial ending in 3 days

Best Practices

Send trial ending emails - Remind customers 3 days before their trial ends.
Make cancellation easy - Customers trust you more when they can leave easily.
Handle failed payments gracefully - Don't lock customers out immediately. Give them time to fix their payment.
Send invoices - Customers like receipts. ClapPay can email invoices automatically.
Offer annual plans - Customers often prefer paying once a year (with a discount) over monthly billing.

Webhooks

Get notified about subscription events

Refunds

How to handle subscription refunds

Card Payments

Save cards for subscriptions

Error Codes

Handle payment failures