Subscriptions API

The Subscriptions API allows you to create and manage recurring billing for your customers.

Build subscription-based revenue models with flexible billing cycles, trial periods, and automatic payment link generation. Perfect for SaaS products, membership sites, and recurring service businesses.

Use Cases

SaaS Products: Monthly or yearly software subscriptions
Membership Sites: Recurring access to premium content
Service Businesses: Retainer agreements and ongoing services
Box Subscriptions: Monthly product deliveries

Available Endpoints

Method	Endpoint	Description
`POST`	`/business/subscription/create`	Create a subscription
`GET`	`/business/subscription/details/:id`	Get subscription details

Subscription Features

Flexible Billing Cycles: Weekly, monthly, quarterly, or yearly
Trial Periods: Offer free or discounted trial periods
Multiple Items: Bundle multiple products in a subscription
Automatic Billing: Recurring payments on schedule
Payment Links: Auto-generated payment links for collection

Billing Cycles

Cycle	Description
`weekly`	Billed every 7 days
`monthly`	Billed every 30 days
`quarterly`	Billed every 90 days
`yearly`	Billed every 365 days

Subscription Statuses

Status	Description
`trial`	In trial period
`active`	Actively billing
`pending`	Awaiting payment
`cancelled`	Cancelled by user
`expired`	Past end date
`paused`	Temporarily paused

Create Subscription

Create a new subscription for a customer.

Endpoint

http

POST /business/subscription/create

Request Body

Field	Type	Required	Description
`customerid`	string	Yes	Customer ID (must exist)
`items`	array	Yes	Subscription items (min: 1)
`billingcycle`	string	No	Billing frequency: `weekly`, `monthly`, `quarterly`, `yearly`
`autorenew`	boolean	No	Auto-renew at end of cycle (default: false)
`trial`	object	No	Trial period configuration
`enddate`	string	No	Subscription end date (ISO 8601)
`paymentmethod`	string	No	Preferred payment method
`remark`	string	No	Internal notes

Item Object

Field	Type	Required	Description
`itemid`	string	Yes	Product ID
`quantity`	integer	Yes	Quantity
`rate`	number	Yes	Price per unit

Trial Object

Field	Type	Required	Description
`startdate`	string	No	Trial start date (ISO 8601). Defaults to now
`enddate`	string	Yes	Trial end date (ISO 8601)

Example Request

cURLJavaScriptPHPPython

bash

curl -X POST "https://api.cashfin.africa/business/subscription/create" \
  -H "Authorization: cs_your_client_secret" \
  -H "Content-Type: application/json" \
  -d '{
    "customerid": "507f1f77bcf86cd799439011",
    "items": [
      {
        "itemid": "507f191e810c19729de860ea",
        "quantity": 1,
        "rate": 2999.00,
        "title": "Pro Plan"
      }
    ],
    "billingcycle": "monthly",
    "autorenew": true,
    "trial": {
      "startdate": "2024-01-15T00:00:00.000Z",
      "enddate": "2024-01-29T23:59:59.000Z"
    }
  }'

javascript

const subscriptionData = {
  customerid: "507f1f77bcf86cd799439011",
  items: [
    {
      itemid: "507f191e810c19729de860ea",
      quantity: 1,
      rate: 2999.0,
      title: "Pro Plan",
    },
  ],
  billingcycle: "monthly",
  autorenew: true,
  trial: {
    startdate: new Date().toISOString(),
    enddate: new Date(Date.now() + 14 * 24 * 60 * 60 * 1000).toISOString(),
  },
};

const response = await fetch(
  "https://api.cashfin.africa/business/subscription/create",
  {
    method: "POST",
    headers: {
      Authorization: "cs_your_client_secret",
      "Content-Type": "application/json",
    },
    body: JSON.stringify(subscriptionData),
  }
);

const data = await response.json();
console.log(data);

php

<?php
$subscriptionData = [
  'customerid' => '507f1f77bcf86cd799439011',
  'items' => [
    [
      'itemid' => '507f191e810c19729de860ea',
      'quantity' => 1,
      'rate' => 2999.00,
      'title' => 'Pro Plan'
    ]
  ],
  'billingcycle' => 'monthly',
  'autorenew' => true,
  'trial' => [
    'startdate' => date('c'),
    'enddate' => date('c', strtotime('+14 days'))
  ]
];

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.cashfin.africa/business/subscription/create",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST => true,
  CURLOPT_POSTFIELDS => json_encode($subscriptionData),
  CURLOPT_HTTPHEADER => [
    "Authorization: cs_your_client_secret",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$result = json_decode($response, true);

print_r($result);

python

import requests
from datetime import datetime, timedelta

subscription_data = {
    'customerid': '507f1f77bcf86cd799439011',
    'items': [
        {
            'itemid': '507f191e810c19729de860ea',
            'quantity': 1,
            'rate': 2999.00,
            'title': 'Pro Plan'
        }
    ],
    'billingcycle': 'monthly',
    'autorenew': True,
    'trial': {
        'startdate': datetime.now().isoformat(),
        'enddate': (datetime.now() + timedelta(days=14)).isoformat()
    }
}

response = requests.post(
    'https://api.cashfin.africa/business/subscription/create',
    headers={
        'Authorization': 'cs_your_client_secret',
        'Content-Type': 'application/json'
    },
    json=subscription_data
)

result = response.json()
print(result)

Success Response

json

{
  "success": true,
  "message": "Subscription created successfully",
  "data": {
    "_id": "507f1f77bcf86cd799439020",
    "subscriptionno": "SUB-2024-001",
    "title": "Pro Plan Subscription",
    "status": "trial",
    "amount": 2999.0,
    "billingcycle": "monthly",
    "autorenew": true,
    "trial": {
      "startdate": "2024-01-15T00:00:00.000Z",
      "enddate": "2024-01-29T23:59:59.000Z",
      "activesubscription": true
    },
    "nextbillingdate": "2024-02-15T00:00:00.000Z",
    "paymentlink": {
      "shorturl": "https://pay.cashfin.africa/xyz789"
    },
    "createdat": "2024-01-15T12:00:00.000Z"
  }
}

Get Subscription Details

Retrieve detailed information about a specific subscription.

Endpoint

http

GET /business/subscription/details/:id

Path Parameters

Parameter	Type	Required	Description
`id`	string	Yes	Subscription ID (MongoDB ObjectID)

Example Request

cURLJavaScriptPHPPython

bash

curl -X GET "https://api.cashfin.africa/business/subscription/details/507f1f77bcf86cd799439020" \
  -H "Authorization: cs_your_client_secret"

javascript

const subscriptionId = "507f1f77bcf86cd799439020";

const response = await fetch(
  `https://api.cashfin.africa/business/subscription/details/${subscriptionId}`,
  {
    headers: {
      Authorization: "cs_your_client_secret",
    },
  }
);

const data = await response.json();
console.log(data);

php

<?php
$subscriptionId = '507f1f77bcf86cd799439020';

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.cashfin.africa/business/subscription/details/{$subscriptionId}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    "Authorization: cs_your_client_secret"
  ],
]);

$response = curl_exec($curl);
$result = json_decode($response, true);

print_r($result);

python

import requests

subscription_id = '507f1f77bcf86cd799439020'

response = requests.get(
    f'https://api.cashfin.africa/business/subscription/details/{subscription_id}',
    headers={
        'Authorization': 'cs_your_client_secret'
    }
)

result = response.json()
print(result)

Success Response

json

{
  "success": true,
  "data": {
    "_id": "507f1f77bcf86cd799439020",
    "subscriptionno": "SUB-2024-001",
    "title": "Pro Plan Subscription",
    "status": "active",
    "amount": 2999.0,
    "fees": 0,
    "billingcycle": "monthly",
    "autorenew": true,
    "channel": "api",
    "trial": {
      "startdate": "2024-01-15T00:00:00.000Z",
      "enddate": "2024-01-29T23:59:59.000Z",
      "activesubscription": true
    },
    "customer": {
      "_id": "507f1f77bcf86cd799439011",
      "name": "John Doe",
      "email": "[email protected]",
      "phone": "+254712345678"
    },
    "items": [
      {
        "itemid": "507f191e810c19729de860ea",
        "title": "Pro Plan",
        "quantity": 1,
        "rate": 2999.0,
        "amount": 2999.0
      }
    ],
    "nextbillingdate": "2024-02-15T00:00:00.000Z",
    "paymentlink": {
      "shorturl": "https://pay.cashfin.africa/xyz789",
      "qrcode": "data:image/png;base64,..."
    },
    "createdat": "2024-01-15T12:00:00.000Z",
    "updatedat": "2024-01-15T12:00:00.000Z"
  }
}

Subscription Lifecycle

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   Created   │────►│   Trial     │────►│   Active    │
└─────────────┘     └─────────────┘     └─────────────┘
                           │                    │
                           │                    ▼
                           │            ┌─────────────┐
                           └───────────►│  Cancelled  │
                                        └─────────────┘
                                               │
                                               ▼
                                        ┌─────────────┐
                                        │   Expired   │
                                        └─────────────┘

Error Responses

Customer Not Found

json

{
  "success": false,
  "message": "Customer not found"
}

Invalid Subscription ID

json

{
  "success": false,
  "message": "Invalid subscription ID"
}

Subscription Not Found

json

{
  "success": false,
  "message": "Subscription not found"
}

Subscriptions API ​

Available Endpoints ​

Subscription Features ​

Billing Cycles ​

Subscription Statuses ​

Create Subscription ​

Endpoint ​

Request Body ​

Item Object ​

Trial Object ​

Example Request ​

Success Response ​

Get Subscription Details ​

Endpoint ​

Path Parameters ​

Example Request ​

Success Response ​

Subscription Lifecycle ​

Error Responses ​

Customer Not Found ​

Invalid Subscription ID ​

Subscription Not Found ​

Subscriptions API

Available Endpoints

Subscription Features

Billing Cycles

Subscription Statuses

Create Subscription

Endpoint

Request Body

Item Object

Trial Object

Example Request

Success Response

Get Subscription Details

Endpoint

Path Parameters

Example Request

Success Response

Subscription Lifecycle

Error Responses

Customer Not Found

Invalid Subscription ID

Subscription Not Found