Overview
ThePlansClient provides read-only access to billing plans. It’s used by merchants’ frontends to render pricing pages and plan selectors. Plan mutations are handled via revstack.admin.plans.
Methods
list()
List plans with optional filters.const response = await revstack.plans.list(params);
// Fetch all public plans for the pricing page
const { data: plans } = await revstack.plans.list({
status: "active",
});
for (const plan of plans) {
console.log(`${plan.name}: ${plan.slug}`);
}
get()
Retrieve a single plan by ID, including its nested prices and entitlements.const plan = await revstack.plans.get(planId);
The plan’s unique identifier.Example:
"plan_pro" or "plan_abc123"The plan with populated
prices[] and entitlements[].Show properties
Show properties
Unique identifier with
plan_ prefix.Human-readable plan name.Example:
"Pro", "Enterprise"URL-safe unique slug.Example:
"pro", "enterprise"Optional plan description for display in pricing pages.
Project this plan belongs to.
Plan status:
draft, active, archived.Plan type:
free, paid, custom.Arbitrary key-value metadata.
Whether this is the default plan assigned to new customers.
Whether this plan is publicly visible in pricing pages.
Associated prices (billing intervals).
Show Price properties
Show Price properties
Unique identifier with
price_ prefix.The plan this price belongs to.
Price amount in the smallest currency unit (e.g. cents).
ISO 4217 currency code. Defaults to
USD.Billing interval:
month, year, week, day.Number of trial days before billing begins.
Whether this price is currently available for new subscriptions.
Associated entitlement allocations.
Show PlanEntitlement properties
Show PlanEntitlement properties
Unique identifier with
plan_ent_ prefix.The plan this allocation belongs to.
The entitlement being allocated.
Numeric usage limit (for metered entitlements).
null = unlimited.Boolean value (for boolean entitlements).
Whether exceeding the limit blocks access.
Reset interval:
monthly, daily, yearly, never.ISO 8601 timestamp of creation.
// Get a specific plan with prices and entitlements
const proPlan = await revstack.plans.get("plan_pro");
console.log(proPlan.name); // "Pro"
console.log(proPlan.prices); // [{ amount: 4900, billingInterval: "month" }]
console.log(proPlan.entitlements); // [{ entitlementId: "ent_api", valueLimit: 10000 }]
Common Use Cases
Pricing Page
// Fetch all active plans for a pricing page
async function getPricingPlans() {
const { data: plans } = await revstack.plans.list({
status: "active",
});
return plans.map(plan => ({
name: plan.name,
slug: plan.slug,
description: plan.description,
prices: plan.prices?.map(price => ({
amount: price.amount / 100, // Convert cents to dollars
currency: price.currency,
interval: price.billingInterval,
})),
}));
}
Plan Comparison Table
// Build a feature comparison matrix
async function buildComparisonMatrix() {
const { data: plans } = await revstack.plans.list({
status: "active",
});
// Get detailed plan info with entitlements
const detailedPlans = await Promise.all(
plans.map(p => revstack.plans.get(p.id))
);
return detailedPlans.map(plan => ({
name: plan.name,
features: plan.entitlements?.map(ent => ({
id: ent.entitlementId,
limit: ent.valueLimit,
enabled: ent.valueBool,
})),
}));
}
Plan Selector UI
// Generate plan options for a dropdown
async function getPlanOptions() {
const { data: plans } = await revstack.plans.list({
status: "active",
});
return plans.map(plan => ({
value: plan.id,
label: plan.name,
monthlyPrice: plan.prices?.find(
p => p.billingInterval === "month"
)?.amount,
}));
}
Find Default Plan
// Get the default plan for new customers
async function getDefaultPlan() {
const { data: plans } = await revstack.plans.list();
return plans.find(plan => plan.isDefault);
}
Check Plan Features
// Check if a plan includes a specific feature
async function planHasFeature(
planId: string,
featureSlug: string
): Promise<boolean> {
const plan = await revstack.plans.get(planId);
return plan.entitlements?.some(
ent => ent.entitlementId === featureSlug
) ?? false;
}