Subscriptions

Currently supports subscription plan creation for NGN, GHS, ZAR, and USD only.

Header	Value
Authorization	Bearer SECRET_KEY (see Authentication)
Content-Type	application/json

See Environments & Base URLs before making requests.

Create Subscription Plan

Endpoint: POST {{baseUrl}}/subscription/api

Sample request:

{
    "name": "Free trial subscription 7",
    "description": "This is a Free trial Subscription Test",
    "frequency": "monthly",
    "currency": "NGN",
    "type": "fixed",
    "amount": 1000,
    "initialAmount": "500",
    "freeTrial": true,
    "freeTrialPeriod": 5,
    "endDate": "2025-06-30",
    "notificationSettings": {
        "freeTrial": { "enabled": true, "period": 3 }
    }
}

Sample response:

{
    "success": true,
    "message": "Success",
    "data": {
        "subscription": {
            "name": "Free trial subscription 7",
            "description": "This is a Free trial Subscription Test",
            "amount": 10,
            "frequency": "monthly",
            "merchantId": "64xxxxxxxx",
            "link": "http:subscription/3935daxxx",
            "currency": "NGN",
            "code": "39xxxxxx",
            "status": "active",
            "deleted": false,
            "endDate": "2025-06-30T00:00:00.000Z",
            "type": "fixed",
            "notificationSettings": { "freeTrial": { "enabled": false, "period": 3 } },
            "_id": "67xxxxxxxxxxxxxxxx",
            "createdAt": "2025-04-02T06:11:42.501Z",
            "updatedAt": "2025-04-02T06:11:42.501Z",
            "__v": 0
        }
    }
}

Deactivate a Subscription Plan

Allows you to cancel or deactivate an active subscription plan.

Endpoint: POST {{baseUrl}}/subscription/api/:planId

Path variable	Required?
planId	Yes

Sample request:

{ 
   "status": "canceled", 
   "reason": "completed" 
}

Sample response:

{
    "success": true,
    "message": "Success",
    "data": {
        "type": "fixed",
        "_id": "67xxxxxxxxxxxxx",
        "name": "Test",
        "description": "Testing subs",
        "amount": 500,
        "frequency": "monthly",
        "merchantId": "66xxxxxxxxxxxxx",
        "link": "http://pay.startbuttonsubscription/b7xxxxxx",
        "currency": "NGN",
        "code": "b7xxxxxx",
        "status": "canceled",
        "deleted": false,
        "numberOfPaymentsExpected": 5
    }
}

Get Subscribers

Retrieves details of all subscribers on a subscription plan, with optional status filtering.

Endpoint: GET {{baseUrl}}/subscribers

Query param	Required?	Description
subscriptionPlanId	Yes	The subscription plan ID
status	No	activated, completed, or cancelled

Note: if a plan wasn't created with an endDate, none is returned for it.

Sample response:

{
    "_id": "609xxxxxxxxxxx",
    "subscriberId": {
        "email": "[e-mail]",
        "nameOnCard": null,
        "deleted": false,
        "createdAt": "2025-03-07T01:28:47.314Z",
        "updatedAt": "2025-03-08T04:07:50.929Z",
        "id": "67xxxxxxxxxxxxxxx"
    }
}

Cancel Subscriber (merchant-facing)

Cancels a subscriber from a subscription plan, removing their access to a previously active plan. Retrieve the subscriber's ID via Get Subscribers first.

Endpoint: PATCH {{baseUrl}}/subscribers/:subscriberId/update-status

Path variable	Required?	Description
subscriberId	Yes	The subscriber's ID

Sample payload:

{
   "status": "canceled", 
   "reason": "this is the end"
 }

Sample response:

{
    "success": true,
    "message": "success",
    "data": {
        "subscriber": {
            "_id": "678xxxxxxxxxxxxx",
            "subscriberId": "678xxxxxxxxxxxx",
            "planId": "678xxxxxxxxxxxxxxxxxxxx",
            "merchantId": "678xxxxxxxxxx",
            "frequency": "monthly",
            "reason": "I don't Know"
        }
    }
}

Cancel Subscription (customer-facing)

Lets you integrate an "unsubscribe"/"cancel" function into your customer-facing UI, allowing a subscriber to opt out themselves. Retrieve the subscriber's ID via Get Subscribers first.

Endpoint: POST {{baseUrl}}/subscribers/cancel-customer-initiated

Sample payload:

{
    "status": "canceled",
    "reason": "service no longer needed" 
}

Sample response (API):

{
    "success": true,
    "message": "Subscription cancelled successfully",
    "data": {
        "subscriber": {
            "_id": "69282ae11xxxxxxx",
            "subscriberId": "69282ae11bcxxxxx",
            "planId": "692823ec86cxxxxxx",
            "merchantId": "68bc35e39xxxxxxxx",
            "frequency": "monthly",
            "amount": 2000,
            "initialAmount": 0,
            "nextPaymentDate": "2025-12-27T10:41:37.711Z",
            "lastPaymentDate": "2025-11-27T10:41:37.711Z",
            "initialLastPaymentDate": "2025-12-27T10:41:37.711Z",
            "endDate": "2026-01-09T00:00:00.000Z",
            "numberOfPayments": 1,
            "status": "canceled",
            "retryCount": 0,
            "createdAt": "2025-11-27T10:41:37.723Z",
            "updatedAt": "2025-11-27T14:08:41.850Z",
            "__v": 0,
            "reason": "unimportant"
        },
        "cancellationOrigin": "CUSTOMER_SELF_SERVICE"
    }
}

Sample webhook event:

{
  "event": "subscription.canceled.customer",
  "data": {
    "subscription": {
      "subscriptionId": "69282ae11bcxxxxxxx",
      "subscriptionPlanId": "692823ec86cedxxxxxx",
      "nameOfPlan": "testing sub",
      "subscriberEmail": "[e-mail]",
      "subscriberName": "",
      "status": "canceled",
      "reason": "unimportant",
      "cancellationOrigin": "CUSTOMER_SELF_SERVICE",
      "source": "Customer-initiated cancellation via merchant UI.",
      "canceledAt": "2025-11-27T14:08:41.897Z"
    }
  }
}

Subscription FAQs

1. How can we identify the subscription plan the user paid for, from the webhook response? The payment code returned in the webhook response matches the code on the subscription link.

2. If a subscription charge attempt fails, will it be retried in the next billing cycle? Yes, until the number of expected payment cycles is completed, it retries in the next billing cycle.