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
`POST`	`/business/subscription/cancel/:id`	Cancel a subscription
`POST`	`/business/subscription/pause/:id`	Pause a subscription
`POST`	`/business/subscription/resume/:id`	Resume a paused subscription
`GET`	`/business/subscription/generate-invoice/:id`	Generate an invoice manually

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"
  }
}

Cancel Subscription

Cancel an active subscription. Once cancelled, it cannot be reactivated.

Endpoint

http

POST /business/subscription/cancel/:id

Path Parameters

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

Request Body

Field	Type	Required	Description
`reason`	string	No	Reason for cancellation

Example Request

cURLJavaScriptPython

bash

curl -X POST "https://api.cashfin.africa/business/subscription/cancel/507f1f77bcf86cd799439020" \
  -H "Authorization: cs_your_client_secret" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Customer requested cancellation"
  }'

javascript

const subscriptionId = "507f1f77bcf86cd799439020";

const response = await fetch(
  `https://api.cashfin.africa/business/subscription/cancel/${subscriptionId}`,
  {
    method: "POST",
    headers: {
      Authorization: "cs_your_client_secret",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      reason: "Customer requested cancellation",
    }),
  }
);

const data = await response.json();

python

import requests

subscription_id = '507f1f77bcf86cd799439020'

response = requests.post(
    f'https://api.cashfin.africa/business/subscription/cancel/{subscription_id}',
    headers={'Authorization': 'cs_your_client_secret'},
    json={'reason': 'Customer requested cancellation'}
)

result = response.json()

Success Response

json

{
  "success": true,
  "message": "Subscription cancelled successfully"
}

Pause Subscription

Temporarily pause an active subscription. Billing stops until the subscription is resumed.

Endpoint

http

POST /business/subscription/pause/:id

Path Parameters

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

Example Request

cURLJavaScriptPython

bash

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

javascript

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

python

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

Success Response

json

{
  "success": true,
  "message": "Subscription paused successfully"
}

Resume Subscription

Resume a paused subscription. Billing resumes from the next billing cycle.

Endpoint

http

POST /business/subscription/resume/:id

Path Parameters

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

Example Request

cURLJavaScriptPython

bash

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

javascript

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

python

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

Success Response

json

{
  "success": true,
  "message": "Subscription resumed successfully"
}

Generate Subscription Invoice

Manually generate a new invoice for an active subscription, outside of the normal billing cycle.

Endpoint

http

GET /business/subscription/generate-invoice/:id

Path Parameters

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

Requirements

The subscription must have active status. Paused, cancelled, or trial subscriptions cannot have invoices manually generated.

Example Request

cURLJavaScriptPython

bash

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

javascript

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

const data = await response.json();

python

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

Success Response

json

{
  "success": true,
  "message": "Invoice generated successfully",
  "data": {
    "invoice": {
      "_id": "507f1f77bcf86cd799439030",
      "invoiceno": "INV-2024-005",
      "status": "unpaid",
      "balance": 2999.0,
      "duedate": "2024-02-15T00:00:00Z"
    },
    "paymentlink": "https://yourbusiness.cashfin.africa/pay/xyz789"
  }
}

Subscription Lifecycle

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   Created   │────►│   Trial     │────►│   Active    │
└─────────────┘     └─────────────┘     └──────┬──────┘
                           │                    │
                           │               ┌────▼────┐
                           │               │ Paused  │
                           │               └────┬────┘
                           │                    │
                           │            ┌───────▼─────┐
                           └───────────►│  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 ​

Cancel Subscription ​

Endpoint ​

Path Parameters ​

Request Body ​

Example Request ​

Success Response ​

Pause Subscription ​

Endpoint ​

Path Parameters ​

Example Request ​

Success Response ​

Resume Subscription ​

Endpoint ​

Path Parameters ​

Example Request ​

Success Response ​

Generate Subscription Invoice ​

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

Cancel Subscription

Endpoint

Path Parameters

Request Body

Example Request

Success Response

Pause Subscription

Endpoint

Path Parameters

Example Request

Success Response

Resume Subscription

Endpoint

Path Parameters

Example Request

Success Response

Generate Subscription Invoice

Endpoint

Path Parameters

Example Request

Success Response

Subscription Lifecycle

Error Responses

Customer Not Found

Invalid Subscription ID

Subscription Not Found