Product Plans

Product plans define what you sell and how you bill for it. Each plan can have multiple prices (e.g., monthly and annual billing). Plans are used with subscriptions.

Create a product plan

Create plantypescript

const plan = await noderails.productPlans.create({
  name: 'Pro Plan',
  description: 'Full access to all features',
  planType: 'SUBSCRIPTION',
  prices: [
    {
      amount: '29.99',
      currency: 'USD',
      billingInterval: 'MONTH',
      billingIntervalCount: 1,
      nickname: 'Monthly',
      isDefault: true,
    },
  ],
});

console.log(plan.id);   // Plan ID
console.log(plan.name); // "Pro Plan"

Add prices to a plan

Each price defines an amount, currency, and billing interval. A plan can have multiple prices so customers can choose between monthly, annual, etc.

Create pricestypescript

// Monthly price
const monthly = await noderails.productPlans.createPrice(plan.id, {
  amount: '29.99',
  currency: 'USD',
  billingInterval: 'MONTH',
  billingIntervalCount: 1,
  nickname: 'Monthly',
});

// Annual price
const annual = await noderails.productPlans.createPrice(plan.id, {
  amount: '299.00',
  currency: 'USD',
  billingInterval: 'YEAR',
  billingIntervalCount: 1,
  nickname: 'Annual',
});

Retrieve a plan

Retrievetypescript

const plan = await noderails.productPlans.retrieve('plan-id');
console.log(plan.name, plan.prices);

Update a plan

Update plantypescript

await noderails.productPlans.update('plan-id', {
  name: 'Pro Plan v2',
  description: 'Updated features',
});

Update a price

Update pricetypescript

await noderails.productPlans.updatePrice('plan-id', 'price-id', {
  nickname: 'Monthly (updated)',
});

Delete a price

Delete pricetypescript

await noderails.productPlans.deletePrice('plan-id', 'price-id');

List plans

Listtypescript

const plans = await noderails.productPlans.list();

for (const plan of plans.data) {
  console.log(plan.id, plan.name, plan.prices.length, 'prices');
}

Methods reference

Method	Description
`create(params)`	Create a new product plan
`retrieve(id)`	Retrieve a plan with prices
`list(params?)`	List all plans
`update(id, params)`	Update a plan
`createPrice(planId, params)`	Add a price to a plan
`updatePrice(planId, priceId, params)`	Update a price
`deletePrice(planId, priceId)`	Remove a price

TypeScript types

Type importstypescript

import type {
  ProductPlan,
  ProductPlanCreateParams,
  ProductPlanPrice,
  PriceCreateParams,
  PriceUpdateParams,
} from '@noderails/sdk';

Response body reference

All responses are wrapped in { success: true, data: ... }. The fields below describe what's inside data.

`create()`, `update()`, and `list()` response

ProductPlan

idstringUnique plan ID (UUID)

appIdstringYour app ID

namestringPlan name

descriptionstring | nullPlan description

imageUrlstring | nullPlan image URL

planTypestring"ONE_TIME" or "SUBSCRIPTION"

taxRateIdstring | nullDefault tax rate ID

isActivebooleanWhether the plan is active

metadataobjectYour metadata key-value pairs

createdAtstringISO 8601 creation timestamp

updatedAtstringISO 8601 last update timestamp

pricesProductPlanPrice[]All prices for this plan (sorted by sortOrder)

taxRateTaxRate | nullFull tax rate object, if linked

ProductPlanPrice (nested in prices[])

idstringUnique price ID (UUID)

productPlanIdstringParent plan ID

appIdstringYour app ID

amountstringPrice amount (Decimal as string, e.g. "29.99")

currencystringCurrency code, default "USD"

billingIntervalstring | nullMONTH, YEAR, WEEK, or DAY

billingIntervalCountnumberIntervals between charges (e.g. 1 for monthly)

trialPeriodDaysnumberFree trial days (default 0)

nicknamestring | nullDisplay name, e.g. "Monthly"

sortOrdernumberDisplay order

isDefaultbooleanWhether this is the default price

isActivebooleanWhether price is active

metadataobjectPrice-level metadata

createdAtstringISO 8601 timestamp

updatedAtstringISO 8601 timestamp

`retrieve()` response

Same as above plus the full app object.

Additional fields on retrieve

appAppFull app object (id, name, environment, etc.)

`createPrice()` and `updatePrice()` response

Returns the single ProductPlanPrice object (no nested plan or tax rate).

`deletePrice()` response

Returns 204 No Content (no response body).