Paystack plans

Paystack Plans

The Plans API lets you create and manage installment/recurring payment options. Plans define the billing cycle, amount, and currency for subscriptions.

Depends on: paystack-setup for the paystackRequest helper.
Related: paystack-subscriptions for subscribing customers to plans.

Endpoints

Method	Endpoint	Description
POST	/plan	Create a plan
GET	/plan	List plans
GET	/plan/:id_or_code	Fetch a plan
PUT	/plan/:id_or_code	Update a plan

Create Plan

POST /plan

Param	Type	Required	Description
name	string	Yes	Name of the plan
amount	integer	Yes	Amount in subunits (e.g. 500000 = ₦5,000)
interval	string	Yes	daily, weekly, monthly, quarterly, biannually, annually
description	string	No	Plan description
send_invoices	boolean	No	Send invoices to customers (default: true)
send_sms	string	No	Send SMS to customers (default: true)
currency	string	No	Currency code e.g. NGN, GHS, ZAR, USD
invoice_limit	integer	No	Max invoices to raise during subscription

const plan = await paystackRequest<{
  name: string;
  plan_code: string;
  amount: number;
  interval: string;
}>("/plan", {
  method: "POST",
  body: JSON.stringify({
    name: "Pro Plan",
    amount: 500000,        // ₦5,000
    interval: "monthly",
    currency: "NGN",
    send_invoices: true,
    invoice_limit: 0,      // 0 = unlimited
  }),
});
// plan.data.plan_code → "PLN_gx2wn530m0i3w3m"

List Plans

GET /plan

Param	Type	Required	Description
perPage	integer	No	Records per page (default: 50)
page	integer	No	Page number (default: 1)
status	string	No	Filter by plan status
interval	string	No	Filter by interval
amount	integer	No	Filter by amount (in subunits)

const plans = await paystackRequest("/plan?perPage=20&page=1&interval=monthly");

Fetch Plan

GET /plan/:id_or_code

Returns plan details including associated subscriptions array.

const plan = await paystackRequest(
  `/plan/${encodeURIComponent("PLN_gx2wn530m0i3w3m")}`
);

Update Plan

PUT /plan/:id_or_code

All body params are the same as Create Plan, plus:

Param	Type	Required	Description
update_existing_subscriptions	boolean	No	Apply changes to existing subscriptions (default: true)

await paystackRequest(`/plan/${encodeURIComponent("PLN_gx2wn530m0i3w3m")}`, {
  method: "PUT",
  body: JSON.stringify({
    name: "Pro Plan (Updated)",
    amount: 750000,
    update_existing_subscriptions: false, // Only affect new subscriptions
  }),
});

Intervals Reference

Interval	Description
daily	Charge every day
weekly	Charge every 7 days
monthly	Charge every month
quarterly	Charge every 3 months
biannually	Charge every 6 months
annually	Charge every 12 months

Common Pattern: SaaS Pricing Setup

async function createPricingTiers() {
  const tiers = [
    { name: "Starter", amount: 200000, interval: "monthly" as const },
    { name: "Pro", amount: 500000, interval: "monthly" as const },
    { name: "Enterprise", amount: 2000000, interval: "monthly" as const },
  ];

  const plans = await Promise.all(
    tiers.map((tier) =>
      paystackRequest("/plan", {
        method: "POST",
        body: JSON.stringify({
          ...tier,
          currency: "NGN",
          send_invoices: true,
        }),
      })
    )
  );

  return plans.map((p: any) => ({
    name: p.data.name,
    code: p.data.plan_code,
    amount: p.data.amount,
  }));
}