Skip to main content
Use these endpoints to create, retrieve, update, and cancel subscriptions. A subscription links a customer to a billing plan and automatically charges the customer’s saved card on the schedule defined by the plan. New subscriptions start in PENDING status and become ACTIVE after the customer completes card setup. Base URL: https://app.kulmipay.com/api/v1/subscriptions/subscriptions/

​
Subscription lifecycle

StatusDescription
PENDINGSubscription created, awaiting customer card setup.
ACTIVECard setup complete; recurring billing is running.
COMPLETEAll billing cycles in the plan have been processed.
CANCELEDSubscription was cancelled via the unsubscribe endpoint.
FAILEDA billing attempt failed. The subscription retries on the next scheduled date.

​
Create a subscription

POST /api/v1/subscriptions/subscriptions/ Creates a new subscription for a customer against a billing plan. The response includes a setup_url — send your customer to this URL to complete card enrollment. The subscription becomes ACTIVE once the customer successfully sets up their payment method.

​
Request parameters

​
plan_id
string
required
The plan_id (alias ID) of the billing plan to subscribe to. Create plans using the plans endpoint.
​
customer_id
string
required
The customer_id (alias ID) of the customer being subscribed. Create customers using the customers endpoint.
​
reference
string
Your internal reference ID for this subscription. Optional. Alphanumeric and standard punctuation characters only, up to 45 characters.
​
redirect_url
string
A URL to redirect the customer to after they complete card setup. If not provided, the plan’s redirect_url is used.
​
start_date
string
The date on which billing should start, in YYYY-MM-DD format. Defaults to today if not specified.
cURL
curl --request POST \
  --url https://app.kulmipay.com/api/v1/subscriptions/subscriptions/ \
  --header "Authorization: Bearer YOUR_SECRET_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "plan_id": "pln_abc123",
    "customer_id": "cus_xyz789",
    "reference": "sub_internal_001"
  }'

​
Get subscription details

GET /api/v1/subscriptions/subscriptions/{subscription_id}/ Returns the full details of a subscription, including the linked customer and plan objects.

​
Update a subscription

PUT /api/v1/subscriptions/subscriptions/{subscription_id}/ Updates the plan or next billing date for an active subscription.
​
plan_id
string
required
The plan_id of the new plan to switch this subscription to.
​
start_date
string
Override the next billing date, in YYYY-MM-DD format. Must be today or a future date.

​
Cancel a subscription

POST /api/v1/subscriptions/subscriptions/{subscription_id}/unsubscribe/ Cancels the subscription immediately. No further charges will be made. The subscription status changes to CANCELED.
cURL
curl --request POST \
  --url https://app.kulmipay.com/api/v1/subscriptions/subscriptions/sub_abc123/unsubscribe/ \
  --header "Authorization: Bearer YOUR_SECRET_KEY"

​
Get subscription payment history

GET /api/v1/subscriptions/subscriptions/{subscription_id}/transactions/ Returns a list of all payment records for this subscription, including the linked invoice for each billing cycle.

​
Subscription object

​
subscription_id
string
The subscription alias ID. Use this value in all subsequent calls to reference this subscription.
​
status
string
Current subscription status: PENDING, ACTIVE, COMPLETE, CANCELED, or FAILED.
​
start_date
string
The date billing started, in YYYY-MM-DD format.
​
next_date
string
The date of the next scheduled billing attempt. null if the subscription is complete or canceled.
​
completed_cycles
number
The number of billing cycles that have been successfully processed.
​
fail_reason
string
The reason for the most recent failed billing attempt. Present only when status is FAILED.
​
setup_url
string
The URL to send the customer to for card enrollment. Required for the subscription to become active.
​
plan
object
The billing plan linked to this subscription. See plans for the full object structure.
​
customer
object
The customer linked to this subscription. See customers for the full object structure.
​
payment_method
string
The payment method used for recurring charges. Currently CARD-PAYMENT.
​
card_mask
string
The masked card number used for billing, for example ****4242. Present after card setup completes.
​
card_type
string
The card network, for example VISA or MASTERCARD. Present after card setup completes.
​
created_at
string
ISO 8601 timestamp of when the subscription was created.

​
Example response

{
  "subscription_id": "sub_abc123",
  "status": "ACTIVE",
  "start_date": "2024-04-01",
  "next_date": "2024-05-01",
  "completed_cycles": 1,
  "fail_reason": null,
  "setup_url": "https://app.kulmipay.com/subscriptions/charge/abc123...",
  "payment_method": "CARD-PAYMENT",
  "card_mask": "****4242",
  "card_type": "VISA",
  "card_expiry": "2026-08-01",
  "plan": {
    "plan_id": "pln_abc123",
    "name": "Monthly Pro",
    "amount": "2999.00",
    "currency": "KES",
    "frequency": 1,
    "frequency_unit": "M",
    "billing_cycles": 12
  },
  "customer": {
    "customer_id": "cus_xyz789",
    "email": "jane@example.com",
    "first_name": "Jane",
    "last_name": "Doe"
  },
  "created_at": "2024-04-01T08:00:00Z",
  "updated_at": "2024-04-01T08:05:32Z"
}