Subscriptions

You can create subscription plans with customizable billing frequencies (daily, weekly, monthly, etc.) and amounts using just a single endpoint.

We currently support creation of subscription plans for NGN, GHS, ZAR, and USD only.

Authorization	Set value to `Bearer SECRET_KEY`
Content-type	Set value to application/json

The secret key can be gotten from the 'Settings' page on your Startbutton dashboard.

Post a request to the URL below, where the base URL is determined by the environment you are in.

BaseUrl

Sandbox/PROD: https://api.startbutton.tech

Create Subscription Plan

Endpoint

POST: {{baseUrl}}/subscription/api

Sample code:

{
    "name": "Free trial subscription 7",
    "description": "This is a Free trial Subscription Test",
    "frequency": "monthly",
    "currency": "NGN",
    "type": "fixed",
    "amount": 1000,
    "initialAmount": "500", //to set first time subscriber amount
    "freeTrial": true, //to enable free trial period
    "freeTrialPeriod": 5, //to set free trial period
    "endDate": "2025-06-30", //this is optional
    "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

This is endpoint allows you cancel or deactivate an active subscription plan

Endpoint

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

Path variable	Required?
planId	Yes

Sample Code:

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

This endpoint retrieves details of all subscribers on a subscription plan and allows filtering by status.

Endpoint

GET: {{baseUrl}}/subscribers

Query Params	Required?	Description
subscriptionPlanId	Yes	the subscription plan id
status	No	should be activated, 'completed', or 'cancelled',

Sample Response:

The Subscription Plan detail associated with the subscriber is also returned, but for the scope of this DOC we will only share the Subscriber's detail. Additionally, if a Subscription Plan isn't created with an endDate— then no endDate is returned for the Plan.

{
    "_id": "609xxxxxxxxxxx", //this is the subscriber's Id
    "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]

With this endpoint, you can cancel a subscriber from a subscription plan. It allows you to remove a subscriber's access to a previously active subscription plan. You need to retrieve the subscriber's Id using the Get-subscriber endpoint 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",
…            "updatedAt": "2025-xxxxxxxxxxxxxxxxxx",
            "reason": "I don't Know"
        }
    }
}

Cancel subscription [customer-facing]

With this endpoint, you can integrate an unsubcribe or cancel function in your customer facing UI for a subscription plan. This functionality allows a subscriber opt-out of an active subscription plan by themselves. You can retrieve the subscriber's Id using the Get-subscriber endpoint first.

Endpoint

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

Sample Payload

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

Sample Response

API response

{
    "success": true,
    "message": "Subscription cancelled successfully",
    "data": {
        "subscriber": {
            "_id": "69282ae11xxxxxxx", //this is the subscriber's id
            "subscriberId": "69282ae11bcxxxxx",
            "planId": "692823ec86cxxxxxx", //this is the susbcriptionPlanid
            "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"
    }
}

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? ANS: The payment code returned in the webhook response would be the same as the code on the subscription link.

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