rexedge/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,
  }));
}