Overview The SubscriptionsClient handles creating, retrieving, canceling, and upgrading/downgrading customer subscriptions.
Methods create() Create a new subscription for a customer.
const subscription = await revstack . subscriptions . create ( params );
params
CreateSubscriptionParams
required
Subscription creation parameters. The customer to subscribe. Example: "usr_abc123"
The plan to subscribe the customer to. Example: "plan_pro"
Optional specific price ID (if the plan has multiple billing intervals). Example: "price_pro_monthly"
The newly created subscription. Unique identifier with sub_ prefix.
Environment this subscription belongs to.
The customer who owns this subscription.
The plan this subscription is for.
The specific price (billing interval) selected.
Current status: active, canceled, past_due, trialing, etc.
Start of the current billing period (ISO 8601).
End of the current billing period (ISO 8601).
Subscription ID in the external payment gateway (e.g. Stripe sub_...).
Per-subscription entitlement overrides.
ISO 8601 timestamp of creation.
Example: const subscription = await revstack . subscriptions . create ({ customerId: "usr_abc123" , planId: "plan_pro" , }); console . log ( `Subscription ${ subscription . id } created` );
get() Retrieve a subscription by ID.
const subscription = await revstack . subscriptions . get ( subscriptionId );
The subscription’s unique identifier. Example: "sub_abc123"
Example: const subscription = await revstack . subscriptions . get ( "sub_abc123" ); console . log ( subscription . status ); // "active"
list() List subscriptions with optional filters.
const response = await revstack . subscriptions . list ( params );
Filter and pagination parameters. Filter by subscription status. Example: "active", "canceled"
Maximum number of records to return.
Number of records to skip.
response
PaginatedResponse<Subscription>
A paginated list of subscriptions. Array of subscription records.
Total number of records matching the query.
Whether more records exist beyond this page.
Example: // Get all active subscriptions for a customer const { data : subscriptions } = await revstack . subscriptions . list ({ customerId: "usr_abc123" , status: "active" , });
cancel() Cancel an active subscription. The subscription will remain active until the end of the current billing period.
const subscription = await revstack . subscriptions . cancel ( subscriptionId );
The subscription to cancel. Example: "sub_abc123"
The updated subscription with canceled status.
Example: const subscription = await revstack . subscriptions . cancel ( "sub_abc123" ); console . log ( subscription . status ); // "canceled"
changePlan() Change the plan of an existing subscription (upgrade or downgrade). Proration is handled automatically by the billing engine.
const subscription = await revstack . subscriptions . changePlan ( subscriptionId , params );
The subscription to modify.
The new plan parameters. The new plan to switch to. Example: "plan_enterprise"
Optional specific price ID for the new plan.
The updated subscription.
Example: // Upgrade a customer from Pro to Enterprise const subscription = await revstack . subscriptions . changePlan ( "sub_abc123" , { newPlanId: "plan_enterprise" } ); console . log ( `Upgraded to ${ subscription . planId } ` );
