Subscriptions
You can create subscription plans with customizable billing frequencies (daily, weekly, monthly, etc.) and amounts using just a single endpoint.
Content-type
Set value to application/json
Post a request to the URL below, where the base URL is determined by the environment you are in.
Create Subscription Plan
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,
"freeTrial": true,
"freeTrialPeriod": 5,
"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
}
}
}
Cancel Subscription
POST: {{baseUrl}}/subscription/api/:planId
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
GET: {{baseUrl}}/subscribers
subscriptionPlanId
Yes
the subscription plan id
status
No
should be activated, 'completed', or 'cancelled',
Sample Response:
{
"_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
PATCH : {{baseUrl}}/subscribers/:subscriberId/update-status
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"
}
}
}
Subscription FAQs
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.
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.
Last updated