Plans API

Plans define the pricing and billing cycle for subscriptions.

The Plan Object

{
  "id": "plan_abc123def456",
  "object": "plan",
  "name": "Pro Monthly",
  "amount": 5000,
  "currency": "GHS",
  "interval": "month",
  "interval_count": 1,
  "trial_period_days": 14,
  "active": true,
  "metadata": {
    "features": "unlimited_access,priority_support"
  },
  "created_at": "2024-01-15T10:00:00Z"
}

Attributes

Attribute	Type	Description
`id`	string	Unique identifier
`object`	string	Always `"plan"`
`name`	string	Plan name
`amount`	integer	Price per interval in pesewas
`currency`	string	Currency code
`interval`	string	`day`, `week`, `month`, `year`
`interval_count`	integer	Intervals between billings
`trial_period_days`	integer	Default trial period
`active`	boolean	Whether plan is active
`metadata`	object	Custom metadata
`created_at`	string	Creation timestamp

Create a Plan

Creates a new plan.

POST /v1/plans

Request Body

Parameter	Type	Required	Description
`name`	string	Yes	Plan name
`amount`	integer	Yes	Price per interval in pesewas
`currency`	string	No	Currency (default: `GHS`)
`interval`	string	Yes	`day`, `week`, `month`, `year`
`interval_count`	integer	No	Intervals between billings (default: 1)
`trial_period_days`	integer	No	Default trial period
`metadata`	object	No	Custom metadata

curl -X POST https://api.44.200.142.19.nip.io/v1/plans \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Pro Monthly",
    "amount": 5000,
    "currency": "GHS",
    "interval": "month",
    "interval_count": 1,
    "trial_period_days": 14,
    "metadata": {
      "features": "unlimited_access,priority_support"
    }
  }'

const plan = await paygate.plans.create({
  name: 'Pro Monthly',
  amount: 5000,
  currency: 'GHS',
  interval: 'month',
  interval_count: 1,
  trial_period_days: 14,
  metadata: {
    features: 'unlimited_access,priority_support'
  }
})

plan = client.plans.create(
    name='Pro Monthly',
    amount=5000,
    currency='GHS',
    interval='month',
    interval_count=1,
    trial_period_days=14,
    metadata={'features': 'unlimited_access,priority_support'}
)

$plan = $paygate->plans->create([
    'name' => 'Pro Monthly',
    'amount' => 5000,
    'currency' => 'GHS',
    'interval' => 'month',
    'interval_count' => 1,
    'trial_period_days' => 14,
    'metadata' => ['features' => 'unlimited_access,priority_support']
]);

Common Billing Intervals

// Monthly
const monthly = await paygate.plans.create({
  name: 'Monthly',
  amount: 5000,
  interval: 'month',
  interval_count: 1
})

// Yearly
const yearly = await paygate.plans.create({
  name: 'Yearly',
  amount: 50000,
  interval: 'year',
  interval_count: 1
})

// Quarterly
const quarterly = await paygate.plans.create({
  name: 'Quarterly',
  amount: 12000,
  interval: 'month',
  interval_count: 3
})

// Bi-weekly
const biweekly = await paygate.plans.create({
  name: 'Bi-weekly',
  amount: 2000,
  interval: 'week',
  interval_count: 2
})

Retrieve a Plan

Retrieves a plan by ID.

GET /v1/plans/:id

curl https://api.44.200.142.19.nip.io/v1/plans/plan_abc123def456 \
  -H "Authorization: Bearer sk_test_..."

const plan = await paygate.plans.retrieve('plan_abc123def456')

plan = client.plans.retrieve('plan_abc123def456')

Update a Plan

Updates a plan. Only name, metadata, and active can be updated.

PATCH /v1/plans/:id

You cannot change the amount, interval, or currency of an existing plan. Create a new plan instead.

Request Body

Parameter	Type	Description
`name`	string	Plan name
`active`	boolean	Whether plan is active
`trial_period_days`	integer	Default trial period
`metadata`	object	Custom metadata

curl -X PATCH https://api.44.200.142.19.nip.io/v1/plans/plan_abc123def456 \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Pro Monthly (Updated)",
    "trial_period_days": 30
  }'

const plan = await paygate.plans.update('plan_abc123def456', {
  name: 'Pro Monthly (Updated)',
  trial_period_days: 30
})

plan = client.plans.update('plan_abc123def456',
    name='Pro Monthly (Updated)',
    trial_period_days=30
)

Delete a Plan

Deletes a plan.

DELETE /v1/plans/:id

Deleting a plan doesn't affect existing subscriptions. They will continue until canceled.

curl -X DELETE https://api.44.200.142.19.nip.io/v1/plans/plan_abc123def456 \
  -H "Authorization: Bearer sk_test_..."

await paygate.plans.delete('plan_abc123def456')

client.plans.delete('plan_abc123def456')

List Plans

Returns a list of plans.

GET /v1/plans

Query Parameters

Parameter	Type	Description
`limit`	integer	Number of results (1-100)
`starting_after`	string	Cursor for pagination
`active`	boolean	Filter by active status

curl "https://api.44.200.142.19.nip.io/v1/plans?active=true&limit=10" \
  -H "Authorization: Bearer sk_test_..."

const plans = await paygate.plans.list({
  active: true,
  limit: 10
})

plans = client.plans.list(active=True, limit=10)

Response

{
  "object": "list",
  "data": [
    {
      "id": "plan_abc123def456",
      "object": "plan",
      "name": "Pro Monthly",
      "amount": 5000,
      ...
    }
  ],
  "has_more": false,
  "url": "/v1/plans"
}

Deactivate a Plan

Instead of deleting, you can deactivate a plan:

const plan = await paygate.plans.update('plan_abc123def456', {
  active: false
})

Deactivated plans:

Cannot be used for new subscriptions
Don't affect existing subscriptions
Can be reactivated later

Plans

On this page