Plans

Overview

A plan defines the price and billing cadence for a subscription. Customers subscribe to plans; plans don't change once created (to avoid retroactively altering existing subscriptions). To change pricing, create a new plan and migrate customers to it.

Create a plan

const plan = await xtopay.plans.create({
  name: "Starter",
  description: "For small teams up to 5 members",
  amount: 2500,         // GHS 25.00
  currency: "GHS",
  interval: "month",    // "day" | "week" | "month" | "year"
  interval_count: 1,    // e.g. 3 = every 3 months
  metadata: {
    feature_seats: "5",
    feature_api_calls: "10000",
  },
});

Billing intervals

Interval	interval_count	Meaning
`month`	`1`	Monthly
`month`	`3`	Quarterly
`month`	`6`	Semi-annual
`year`	`1`	Annual
`week`	`2`	Bi-weekly

Plan object

{
  "id": "plan_a1b2c3",
  "name": "Starter",
  "amount": 2500,
  "currency": "GHS",
  "interval": "month",
  "interval_count": 1,
  "active": true,
  "subscription_count": 148,
  "created_at": "2026-01-01T00:00:00Z"
}

Archiving plans

Plans cannot be deleted if they have active subscriptions. Archive a plan to stop new subscriptions without affecting existing ones:

await xtopay.plans.archive("plan_a1b2c3");

Archived plans still renew their existing subscribers — they just don't appear as options for new sign-ups.

Multiple currencies

Create separate plans per currency. Xtopay does not auto-convert:

const planGHS = await xtopay.plans.create({ amount: 5000, currency: "GHS", ... });
const planNGN = await xtopay.plans.create({ amount: 250000, currency: "NGN", ... });
const planUSD = await xtopay.plans.create({ amount: 1500, currency: "USD", ... });