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)subscription = commet.subscriptions.create(
customer_id="user_123",
plan_code="pro",
)
redirect(subscription.data["checkout_url"])subscription, err := client.Subscriptions.Create(ctx, &commet.CreateSubscriptionParams{
CustomerID: "user_123",
PlanCode: "pro",
})
redirect(subscription.Data.CheckoutURL)var subscription = commet.subscriptions().create("user_123", "pro");
redirect(subscription.getData().get("checkout_url"));$subscription = $commet->subscriptions->create(
customerId: 'user_123',
planCode: 'pro',
);
redirect($subscription->data['checkout_url']);curl -X POST https://commet.co/api/subscriptions \
-H "x-api-key: $COMMET_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"customerId": "user_123",
"planCode": "pro"
}'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
}sub = commet.subscriptions.get("user_123")
if sub.data and sub.data["status"] == "active":
# User has paidsub, err := client.Subscriptions.Get(ctx, "user_123")
if sub.Data != nil && sub.Data.Status == "active" {
// User has paid
}var sub = commet.subscriptions().get("user_123");
if ("active".equals(sub.getData().get("status"))) {
// User has paid
}$sub = $commet->subscriptions->get('user_123');
if ($sub->data['status'] === 'active') {
// User has paid
}curl "https://commet.co/api/subscriptions/active?customerId=user_123" \
-H "x-api-key: $COMMET_API_KEY"Cancel
await commet.subscriptions.cancel({
subscriptionId: 'sub_xxx',
})commet.subscriptions.cancel(subscription_id="sub_xxx")_, err := client.Subscriptions.Cancel(ctx, &commet.CancelSubscriptionParams{
SubscriptionID: "sub_xxx",
})commet.subscriptions().cancel("sub_xxx");$commet->subscriptions->cancel(subscriptionId: 'sub_xxx');curl -X POST https://commet.co/api/subscriptions/sub_xxx/cancel \
-H "x-api-key: $COMMET_API_KEY"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?