Subscriptions

Subscriptions let you charge customers on a recurring basis. You can configure flexible billing intervals, trials, and upgrade/downgrade options.

What is a Subscription

A subscription links a customer to a product with a specific pricing plan. It defines how often they’re billed and what features they get.

Creating a Subscription

You can create a subscription through the dashboard or API.

Dashboard steps:

1. Go to Customers → Create Subscription

2. Select a product and pricing plan

3. Add coupon or trial if needed

4. Confirm and activate

API example:

curl -X POST https://api.saasapp.com/v1/subscriptions \
  -H "Authorization: Bearer <API_KEY>" \
  -d customer_id=cus_123 \
  -d plan=pro_monthly \
  -d trial_period_days=14

Subscription Lifecycle

Subscriptions go through different states:

Configure retry logic for failed payments to reduce churn.

Free Trials

You can add trial periods to subscriptions:

{
  "customer_id": "cus_123",
  "plan": "basic_monthly",
  "trial_period_days": 7
}

Trials automatically convert to paid subscriptions unless canceled before the trial ends.

Upgrades and Downgrades

Customers can switch between plans at any time.

• Upgrades are prorated by default (only pay the difference).

• Downgrades take effect at the next billing cycle.

Example:

curl -X POST https://api.saasapp.com/v1/subscriptions/sub_123/update \
  -H "Authorization: Bearer <API_KEY>" \
  -d plan=business_annual

Pausing and Resuming

You can temporarily pause subscriptions instead of canceling.

# Pause subscription
curl -X POST https://api.saasapp.com/v1/subscriptions/sub_123/pause \
  -H "Authorization: Bearer <API_KEY>"

Paused subscriptions stop billing but keep customer data intact.

Canceling a Subscription

Subscriptions can be canceled immediately or at the end of the billing period.

# Cancel at end of period
curl -X POST https://api.saasapp.com/v1/subscriptions/sub_123/cancel \
  -H "Authorization: Bearer <API_KEY>" \
  -d at_period_end=true

Summary

• Subscriptions connect customers to recurring plans

• Support trials, upgrades, downgrades, and pauses

• Lifecycle states define how subscriptions behave

• Always test subscription flows in Sandbox before launch