# 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 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
{% 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.
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://startbutton.gitbook.io/startbutton-product-api/startbutton-api-doc/subscriptions.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.