Skip to main content
POST
/
v1
/
plans
Create a plan
curl --request POST \
  --url https://api.useplinth.com/v1/plans \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "plan_group_id": "pg_01JABC...",
  "name": "Pro",
  "amount_minor": 500000,
  "billing_interval": "month",
  "lookup_key": "pro_monthly",
  "billing_interval_count": 1,
  "trial_period_days": 14
}
'
{
  "object": "plan",
  "id": "pln_01JABC...",
  "name": "Pro",
  "amount_minor": "500000",
  "lookup_key": "pro_monthly",
  "created_at": "2026-06-01T00:00:00Z"
}

Authorizations

​
Authorization
string
header
required

Use sk_test_ keys for sandbox. Use sk_live_ keys for production. Obtain your key from the dashboard.

Body

application/json
​
plan_group_id
string
required
Example:

"pg_01JABC..."

​
name
string
required
Maximum string length: 100
Example:

"Pro"

​
amount_minor
integer
required

Price in kobo. ₦5,000 = 500000.

Example:

500000

​
billing_interval
enum<string>
required
Available options:
day,
week,
month,
year
Example:

"month"

​
lookup_key
string
required

Required. Stable handle (lowercase letters, numbers, underscores), unique per tenant. Reference this instead of the UUID. Reusing an existing key returns 409.

Pattern: ^[a-z0-9_]+$
Example:

"pro_monthly"

​
billing_interval_count
integer
default:1

e.g., 3 months = interval "month" + count 3

Example:

1

​
trial_period_days
integer
default:0
Example:

14

Response

Plan created

​
object
enum<string>
Available options:
plan
​
id
string
Example:

"pln_01JABC..."

​
plan_group_id
string
Example:

"pg_01JABC..."

​
name
string
Example:

"Pro"

​
amount_minor
string

Amount in kobo as a string. ₦5,000 = "500000".

Example:

"500000"

​
interval
enum<string>
Available options:
day,
week,
month,
year
Example:

"month"

​
interval_count
integer
Example:

1

​
trial_period_days
integer
Example:

14

​
lookup_key
string | null

Stable, human-meaningful handle for the plan (e.g. "pro_monthly"). Unique per tenant. Reference this instead of the UUID so your app doesn't hardcode environment-specific ids.

Example:

"pro_monthly"

​
active
boolean

false when the plan is archived — hidden from the default plan list and closed to new subscriptions. Existing subscribers keep billing.

Example:

true

​
created_at
string<date-time>