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(
    CreateSubscriptionParams.builder("user_123").planCode("pro").build()
);

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`	`weekly`, `monthly`, `quarterly`, `yearly`, or `one_time`
`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.getActive({ customerId: 'user_123' })

if (sub.data?.status === 'active') {
  // User has paid
}

sub = commet.subscriptions.get_active(customer_id="user_123")

if sub.data and sub.data["status"] == "active":
    # User has paid

sub, err := client.Subscriptions.GetActive(ctx, &commet.GetActiveSubscriptionParams{
    CustomerID: "user_123",
})

if sub.Data != nil && sub.Data.Status == "active" {
    // User has paid
}

var sub = commet.subscriptions().getActive(GetActiveSubscriptionParams.builder("user_123").build());

if ("active".equals(sub.getData().get("status"))) {
    // User has paid
}

$sub = $commet->subscriptions->getActive('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"

Get a subscription by ID

getActive returns a customer's current active subscription. To fetch a specific subscription by its ID — regardless of status, including pending_payment and past_due — use get.

const sub = await commet.subscriptions.get({ id: 'sub_xxx' })

sub = commet.subscriptions.get("sub_xxx")

sub, err := client.Subscriptions.Get(ctx, "sub_xxx")

var sub = commet.subscriptions().get("sub_xxx");

$sub = $commet->subscriptions->get('sub_xxx');

curl "https://commet.co/api/subscriptions/sub_xxx" \
  -H "x-api-key: $COMMET_API_KEY"

Cancel

await commet.subscriptions.cancel({
  id: 'sub_xxx',
})

commet.subscriptions.cancel("sub_xxx")

_, err := client.Subscriptions.Cancel(ctx, "sub_xxx", &commet.CancelSubscriptionParams{})

commet.subscriptions().cancel("sub_xxx", CancelSubscriptionParams.builder().build());

$commet->subscriptions->cancel('sub_xxx');

curl -X POST https://commet.co/api/subscriptions/sub_xxx/cancel \
  -H "x-api-key: $COMMET_API_KEY"

By default, the subscription remains active until the end of the current billing period. Any pending metered usage will be billed in the final invoice.

Cancel immediately

Only use this when the customer has violated your terms of service or you are banning them. For regular cancellations, use the default cancel above — it respects the period the customer already paid for and schedules the cancellation at period end. Canceling immediately revokes access right away without refunding the remaining time.

To cancel a subscription right now instead of at period end, pass immediate: true. The subscription status changes to canceled and the end date is set to now.

await commet.subscriptions.cancel({
  id: 'sub_xxx',
  immediate: true,
})

commet.subscriptions.cancel("sub_xxx", immediate=True)

immediate := true
_, err := client.Subscriptions.Cancel(ctx, "sub_xxx", &commet.CancelSubscriptionParams{
    Immediate: &immediate,
})

commet.subscriptions().cancel("sub_xxx", CancelSubscriptionParams.builder().immediate(true).build());

$commet->subscriptions->cancel('sub_xxx', immediate: true);

curl -X POST https://commet.co/api/subscriptions/sub_xxx/cancel \
  -H "x-api-key: $COMMET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"immediate": true}'

Canceled subscriptions cannot be reactivated — create a new one.

Learn more

How Does Billing Work

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

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

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(
    CreateSubscriptionParams.builder("user_123").planCode("pro").build()
);

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`	`weekly`, `monthly`, `quarterly`, `yearly`, or `one_time`
`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.getActive({ customerId: 'user_123' })

if (sub.data?.status === 'active') {
  // User has paid
}

sub = commet.subscriptions.get_active(customer_id="user_123")

if sub.data and sub.data["status"] == "active":
    # User has paid

sub, err := client.Subscriptions.GetActive(ctx, &commet.GetActiveSubscriptionParams{
    CustomerID: "user_123",
})

if sub.Data != nil && sub.Data.Status == "active" {
    // User has paid
}

var sub = commet.subscriptions().getActive(GetActiveSubscriptionParams.builder("user_123").build());

if ("active".equals(sub.getData().get("status"))) {
    // User has paid
}

$sub = $commet->subscriptions->getActive('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"

Get a subscription by ID

getActive returns a customer's current active subscription. To fetch a specific subscription by its ID — regardless of status, including pending_payment and past_due — use get.

const sub = await commet.subscriptions.get({ id: 'sub_xxx' })

sub = commet.subscriptions.get("sub_xxx")

sub, err := client.Subscriptions.Get(ctx, "sub_xxx")

var sub = commet.subscriptions().get("sub_xxx");

$sub = $commet->subscriptions->get('sub_xxx');

curl "https://commet.co/api/subscriptions/sub_xxx" \
  -H "x-api-key: $COMMET_API_KEY"

Cancel

await commet.subscriptions.cancel({
  id: 'sub_xxx',
})

commet.subscriptions.cancel("sub_xxx")

_, err := client.Subscriptions.Cancel(ctx, "sub_xxx", &commet.CancelSubscriptionParams{})

commet.subscriptions().cancel("sub_xxx", CancelSubscriptionParams.builder().build());

$commet->subscriptions->cancel('sub_xxx');

curl -X POST https://commet.co/api/subscriptions/sub_xxx/cancel \
  -H "x-api-key: $COMMET_API_KEY"

By default, the subscription remains active until the end of the current billing period. Any pending metered usage will be billed in the final invoice.

Cancel immediately

To cancel a subscription right now instead of at period end, pass immediate: true. The subscription status changes to canceled and the end date is set to now.

await commet.subscriptions.cancel({
  id: 'sub_xxx',
  immediate: true,
})

commet.subscriptions.cancel("sub_xxx", immediate=True)

immediate := true
_, err := client.Subscriptions.Cancel(ctx, "sub_xxx", &commet.CancelSubscriptionParams{
    Immediate: &immediate,
})

commet.subscriptions().cancel("sub_xxx", CancelSubscriptionParams.builder().immediate(true).build());

$commet->subscriptions->cancel('sub_xxx', immediate: true);

curl -X POST https://commet.co/api/subscriptions/sub_xxx/cancel \
  -H "x-api-key: $COMMET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"immediate": true}'

Canceled subscriptions cannot be reactivated — create a new one.

Learn more

How Does Billing Work

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

Manage Subscriptions

Subscription lifecycle

Dashboard management

Create a subscription

Parameters

Get subscription

Get a subscription by ID

Cancel

Cancel immediately

Learn more

On this page

Manage Subscriptions

Subscription lifecycle

Dashboard management

Create a subscription

Parameters

Get subscription

Get a subscription by ID

Cancel

Cancel immediately

Learn more

On this page