Skip to main content
Use these endpoints to create and manage billing plans. A plan defines how much to charge, in which currency, how often, and for how many cycles. Every subscription must be linked to a plan. Updating a plan’s details takes effect for future billing cycles on active subscriptions. Base URL: https://app.kulmipay.com/api/v1/subscriptions/plans/ The POST endpoint performs an upsert: if a plan with the given name already exists on your account, the request updates it instead of creating a duplicate. Plan names are unique per business account.

​
Create or update a plan

POST /api/v1/subscriptions/plans/

​
Request parameters

​
name
string
required
The plan name. This is the unique key — if a plan with this name already exists on your account, the request updates it. Alphanumeric characters only, up to 32 characters.
​
amount
string
required
The billing amount per cycle, as a decimal string, for example "2999.00".
​
currency
string
required
The currency for billing. One of: KES, USD, EUR, GBP.
​
frequency
number
required
The number of frequency_unit intervals between billing cycles. For example, a value of 1 with frequency_unit M means charge every 1 month.
​
frequency_unit
string
The unit of billing frequency. One of:
  • D — daily
  • W — weekly
  • M — monthly (default)
  • Y — yearly
​
billing_cycles
number
default:"11"
The total number of times the customer should be billed. After billing_cycles successful charges, the subscription moves to COMPLETE. Defaults to 11.
​
reference
string
Your internal reference ID for this plan, up to 45 characters.
​
redirect_url
string
A URL to redirect the customer to after they complete card setup for a subscription on this plan. Can be overridden per subscription.
cURL
curl --request POST \
  --url https://app.kulmipay.com/api/v1/subscriptions/plans/ \
  --header "Authorization: Bearer YOUR_SECRET_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "Monthly Pro",
    "amount": "2999.00",
    "currency": "KES",
    "frequency": 1,
    "frequency_unit": "M",
    "billing_cycles": 12
  }'

​
List plans

GET /api/v1/subscriptions/plans/ Returns all billing plans on your account, ordered by creation date (newest first).

​
Retrieve a plan

GET /api/v1/subscriptions/plans/{plan_id}/ Returns a single plan by its plan_id (alias ID).

​
Plan object

​
plan_id
string
The plan alias ID. Use this value as plan_id when creating a subscription.
​
name
string
The plan name.
​
amount
string
The billing amount per cycle.
​
currency
string
The billing currency.
​
frequency
number
The number of frequency_unit intervals between billing cycles.
​
frequency_unit
string
The billing frequency unit. One of D, W, M, or Y.
​
billing_cycles
number
The total number of billing cycles before the subscription completes.
​
reference
string
Your internal reference ID.
​
plan_url
string
A hosted Kulmi Pay page for this plan. You can share this URL with customers to let them subscribe directly without a custom integration.
​
redirect_url
string
The URL customers are redirected to after card setup.
​
created_at
string
ISO 8601 timestamp of when the plan was created.
​
updated_at
string
ISO 8601 timestamp of the last update to this plan.

​
Example response

{
  "plan_id": "pln_abc123",
  "name": "Monthly Pro",
  "amount": "2999.00",
  "currency": "KES",
  "frequency": 1,
  "frequency_unit": "M",
  "billing_cycles": 12,
  "reference": null,
  "plan_url": "https://app.kulmipay.com/subscriptions/charge/pln_abc123/plan/",
  "redirect_url": "https://yourapp.example.com/subscription/success",
  "created_at": "2024-03-01T09:00:00Z",
  "updated_at": "2024-04-10T11:30:00Z"
}
Changing the amount or currency on an existing plan takes effect for the next billing cycle on all active subscriptions linked to it. Subscribers are not notified automatically — communicate pricing changes to your customers before updating a live plan.