Manage Subscriptions
Manage the complete lifecycle of customer subscriptions.
Subscriptions connect a customer to a plan and handle recurring billing automatically. Each customer can have one active subscription at a time. Create one via the SDK or dashboard, and Commet manages checkout, invoicing, and lifecycle transitions.
Subscription lifecycle
| State | Description | Example |
|---|---|---|
| Draft | Created but not yet activated | Subscription just assigned, no checkout sent |
| Trialing | Free trial period active | 14-day trial on the Pro plan |
| Pending Payment | Checkout sent, awaiting payment | Customer received checkout link but hasn't paid |
| Active | Billing normally | Monthly invoice paid, features enabled |
| Paused | Temporarily paused, no billing | Customer requested a break |
| Past Due | Payment failed, in grace period | Card declined, retry scheduled |
| Canceled | No longer billing | Customer canceled or end-of-period reached |
| Expired | Reached scheduled end date | Fixed-term subscription ended |
Dashboard management
From the customer detail page, you can assign a plan, change plans, cancel, or regenerate a checkout link if the original expired. If your plans are in a Plan Group, customers can also change plans themselves through the Customer Portal.
Create a subscription
const subscription = await commet.subscriptions.create({
customerId: 'user_123',
planCode: 'pro',
})
redirect(subscription.data.checkoutUrl)Returns a checkoutUrl — redirect the user there to complete payment.
Parameters
| Parameter | Type | Description |
|---|---|---|
customerId | string | Commet customer ID (cus_xxx) or your external ID |
planCode | string | Plan code (alternative to planId) |
planId | string | Plan UUID (alternative to planCode) |
billingInterval | string | monthly, quarterly, or yearly |
initialSeats | object | Seat type codes mapped to quantities |
skipTrial | boolean | Skip the plan's trial period |
successUrl | string | Redirect URL after successful payment |
Get subscription
const sub = await commet.subscriptions.get('user_123')
if (sub.data?.status === 'active') {
// User has paid
}Cancel
await commet.subscriptions.cancel('sub_xxx')The subscription will remain active until the end of the current billing period. Any pending metered usage will be billed in the final invoice.
Canceled subscriptions cannot be reactivated — create a new one.
Learn more
Related
- Manage Plans — Create pricing plans that drive subscriptions
- Upgrade and Downgrade Plans — How plan changes work
- Trial Periods — Configure free trial periods
- Customer Portal — Self-service billing portal for customers
How is this guide?