# Subscriptions {% hint style="info" %} We currently support creation of subscription plans for NGN, GHS, ZAR, and USD only. {% endhint %} | Authorization | Set value to \`Bearer SECRET\_KEY\` | | ------------- | ----------------------------------- | | Content-type | Set value to `application/json` | {% hint style="info" %} The secret key can be gotten from the 'Settings' page on your Startbutton dashboard. {% endhint %} Post a request to the URL below, where the base URL is determined by the environment you are in.
BaseUrl Sandbox/PROD: ;
### Create Subscription Plan {% tabs %} {% tab title="Endpoint" %} **POST**: `{{baseUrl}}/subscription/api` {% endtab %} {% endtabs %} 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 {% hint style="info" %} This is endpoint allows you cancel or deactivate an active subscription plan {% endhint %} {% tabs %} {% tab title="Endpoint" %} **POST**: `{{baseUrl}}/subscription/api/:planId` {% endtab %} {% endtabs %}
Path variableRequired?
planIdYes
**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 {% hint style="info" %} This endpoint retrieves details of all subscribers on a subscription plan and allows filtering by status. {% endhint %} {% tabs %} {% tab title="Endpoint" %} **GET:** `{{baseUrl}}/subscribers` {% endtab %} {% endtabs %} | Query Params | Required? | Description | | ------------------ | --------- | ------------------------------------------------- | | subscriptionPlanId | Yes | the subscription plan id | | status | No | should be activated, 'completed', or 'cancelled', | Sample Response: {% hint style="info" %} 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. {% endhint %} ``` { "_id": "609xxxxxxxxxxx", //this is the subscriber's Id "subscriberId": { "email": "test@test.com", "nameOnCard": null, "deleted": false, "createdAt": "2025-03-07T01:28:47.314Z", "updatedAt": "2025-03-08T04:07:50.929Z", "id": "67xxxxxxxxxxxxxxx" } } ``` ### Cancel Subscriber \[merchant-facing] {% hint style="info" %} 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](#get-subscribers) first. {% endhint %} {% tabs %} {% tab title="Endpoint" %} **PATCH** `: {{baseUrl}}/subscribers/:subscriberId/update-status` {% endtab %} {% endtabs %} | 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] {% hint style="info" %} 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](#get-subscribers) first. {% endhint %} {% tabs %} {% tab title="Endpoint" %} POST: `{{baseUrl}}/subscribers/cancel-customer-initiated` {% endtab %} {% endtabs %} **Sample Payload** ``` { "status": "canceled", "reason": "service no longer needed" } ``` **Sample Response** {% tabs %} {% tab title="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" } } ``` {% endtab %} {% tab title="Webhook event" %} ``` { "event": "subscription.canceled.customer", "data": { "subscription": { "subscriptionId": "69282ae11bcxxxxxxx", "subscriptionPlanId": "692823ec86cedxxxxxx", "nameOfPlan": "testing sub", "subscriberEmail": "tester@yopmail.com", "subscriberName": "", "status": "canceled", "reason": "unimportant", "cancellationOrigin": "CUSTOMER_SELF_SERVICE", "source": "Customer-initiated cancellation via merchant UI.", "canceledAt": "2025-11-27T14:08:41.897Z" } } } ``` {% endtab %} {% endtabs %} ### 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.