Subscription
A collection of endpoints for creating and managing recurring payments
Copy link List Subscriptions
List all subscriptions available on your integration
Query Parameters
Number of records to fetch per page
The section to retrieve
Plan ID
Customer ID
The start date
The end date
Response
200Subscription List response
5 object properties
GET
/subscriptioncurl https://api.paystack.co/subscription \
-H "Authorization: Bearer YOUR_SECRET_KEY"import { Paystack } from "@paystack/paystack-sdk";
const paystack = new Paystack({ secretKey: process.env.PAYSTACK_SECRET_KEY! });
const response = await paystack.subscription.list({
perPage: 100,
page: 100
});
console.log(response.data);require "paystack"
paystack = Paystack::Client.new(ENV.fetch("PAYSTACK_SECRET_KEY"))
response = paystack.subscription.list({
per_page: 100,
page: 100
})
puts response.dataResponse
{
"status": true,
"message": "Subscriptions retrieved",
"data": [
{
"customer": {
"first_name": "BoJack",
"last_name": "Horseman",
"email": "[email protected]",
"phone": "",
"metadata": null,
"domain": "test",
"customer_code": "CUS_hdhye17yj8qd2tx",
"risk_action": "default",
"id": 84312,
"integration": 100073,
"createdAt": "2016-10-01T10:59:52.000Z",
"updatedAt": "2016-10-01T10:59:52.000Z"
},
"plan": {
"domain": "test",
"name": "Weekly small chops",
"plan_code": "PLN_0as2m9n02cl0kp6",
"description": "Small chops delivered every week",
"amount": 27000,
"interval": "weekly",
"send_invoices": true,
"send_sms": true,
"hosted_page": false,
"hosted_page_url": null,
"hosted_page_summary": null,
"currency": "NGN",
"migrate": null,
"id": 1716,
"integration": 100073,
"createdAt": "2016-10-01T10:59:11.000Z",
"updatedAt": "2016-10-01T10:59:11.000Z"
},
"integration": 123456,
"authorization": {
"authorization_code": "AUTH_6tmt288t0o",
"bin": "408408",
"last4": "4081",
"exp_month": "12",
"exp_year": "2020",
"channel": "card",
"card_type": "visa visa",
"bank": "TEST BANK",
"country_code": "NG",
"brand": "visa",
"reusable": true,
"signature": "SIG_uSYN4fv1adlAuoij8QXh",
"account_name": "BoJack Horseman"
},
"domain": "test",
"start": 1475319599,
"status": "active",
"quantity": 1,
"amount": 27000,
"subscription_code": "SUB_6phdx225bavuwtb",
"email_token": "ore84lyuwcv2esu",
"easy_cron_id": "275226",
"cron_expression": "0 0 * * 6",
"next_payment_date": "2016-10-15T00:00:00.000Z",
"open_invoice": "INV_qc875pkxpxuyodf",
"id": 4192,
"createdAt": "2016-10-01T10:59:59.000Z",
"updatedAt": "2016-10-12T07:45:14.000Z"
}
],
"meta": {
"total": 1,
"skipped": 0,
"perPage": 50,
"page": 1,
"pageCount": 1
}
}{
"status": false,
"message": "An error occurred",
"meta": {
"nextStep": "string"
},
"type": "string",
"code": "validation_error",
"errorCodeMappingNotFound": true
}{
"status": false,
"message": "An error occurred",
"meta": {
"nextStep": "string"
},
"type": "string",
"code": "validation_error",
"errorCodeMappingNotFound": true
}Copy link Create Subscription
Create a subscription a customer
Request Body
Customer's email address or customer code
Plan code
If customer has multiple authorizations, you can set the desired authorization you wish to use for this subscription here.
If this is not supplied, the customer's most recent authorization would be used
Set the date for the first debit. (ISO 8601 format) e.g. 2017-05-16T00:30:13+01:00
Response
200Subscription Create response
22 object properties
POST
/subscriptioncurl https://api.paystack.co/subscription \
-H "Authorization: Bearer YOUR_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{
"customer": "CUS_xnxdt6s1zg1f4nx",
"plan": "PLN_gx2wn530m0i3w3m"
}' \
-X POSTimport { Paystack } from "@paystack/paystack-sdk";
const paystack = new Paystack({ secretKey: process.env.PAYSTACK_SECRET_KEY! });
const response = await paystack.subscription.create({
customer: "CUS_xnxdt6s1zg1f4nx",
plan: "PLN_gx2wn530m0i3w3m"
});
console.log(response.data);require "paystack"
paystack = Paystack::Client.new(ENV.fetch("PAYSTACK_SECRET_KEY"))
response = paystack.subscription.create({
customer: "CUS_xnxdt6s1zg1f4nx",
plan: "PLN_gx2wn530m0i3w3m"
})
puts response.dataResponse
{
"status": true,
"message": "Subscription successfully created",
"data": {
"customer": 1173,
"plan": 28,
"integration": 100032,
"domain": "test",
"start": 1459296064,
"status": "active",
"quantity": 1,
"amount": 50000,
"authorization": {
"authorization_code": "AUTH_6tmt288t0o",
"bin": "408408",
"last4": "4081",
"exp_month": "12",
"exp_year": "2020",
"channel": "card",
"card_type": "visa visa",
"bank": "TEST BANK",
"country_code": "NG",
"brand": "visa",
"reusable": true,
"signature": "SIG_uSYN4fv1adlAuoij8QXh",
"account_name": "BoJack Horseman"
},
"subscription_code": "SUB_vsyqdmlzble3uii",
"email_token": "d7gofp6yppn3qz7",
"id": 9,
"createdAt": "2016-03-30T00:01:04.687Z",
"updatedAt": "2016-03-30T00:01:04.687Z"
}
}{
"status": false,
"message": "An error occurred",
"meta": {
"nextStep": "string"
},
"type": "string",
"code": "validation_error",
"errorCodeMappingNotFound": true
}Copy link Fetch Subscription
Get details of a customer's subscription
Path Parameters
The subscription code for the subscription you want to fetch
Response
200Subscription Fetch response
22 object properties
9 object properties
13 object properties
9 object properties
GET
/subscription/{code}curl https://api.paystack.co/subscription/SUB_5co81xgmwg78x3d \
-H "Authorization: Bearer YOUR_SECRET_KEY"import { Paystack } from "@paystack/paystack-sdk";
const paystack = new Paystack({ secretKey: process.env.PAYSTACK_SECRET_KEY! });
const response = await paystack.subscription.fetch("SUB_5co81xgmwg78x3d");
console.log(response.data);require "paystack"
paystack = Paystack::Client.new(ENV.fetch("PAYSTACK_SECRET_KEY"))
response = paystack.subscription.fetch("SUB_5co81xgmwg78x3d")
puts response.dataResponse
{
"status": true,
"message": "Subscription retrieved successfully",
"data": {
"invoices": [],
"customer": {
"first_name": "BoJack",
"last_name": "Horseman",
"email": "[email protected]",
"phone": null,
"metadata": {
"photos": [
{
"type": "twitter",
"typeId": "twitter",
"typeName": "Twitter",
"url": "https://d2ojpxxtu63wzl.cloudfront.net/static/61b1a0a1d4dda2c9fe9e165fed07f812_a722ae7148870cc2e33465d1807dfdc6efca33ad2c4e1f8943a79eead3c21311",
"isPrimary": false
}
]
},
"domain": "test",
"customer_code": "CUS_xnxdt6s1zg1f4nx",
"id": 1173,
"integration": 100032,
"createdAt": "2016-03-29T20:03:09.000Z",
"updatedAt": "2016-03-29T20:53:05.000Z"
},
"plan": {
"domain": "test",
"name": "Monthly retainer (renamed)",
"plan_code": "PLN_gx2wn530m0i3w3m",
"description": null,
"amount": 50000,
"interval": "monthly",
"send_invoices": true,
"send_sms": true,
"hosted_page": false,
"hosted_page_url": null,
"hosted_page_summary": null,
"currency": "NGN",
"id": 28,
"integration": 100032,
"createdAt": "2016-03-29T22:42:50.000Z",
"updatedAt": "2016-03-29T23:51:41.000Z"
},
"integration": 100032,
"authorization": {
"authorization_code": "AUTH_6tmt288t0o",
"bin": "408408",
"last4": "4081",
"exp_month": "12",
"exp_year": "2020",
"channel": "card",
"card_type": "visa visa",
"bank": "TEST BANK",
"country_code": "NG",
"brand": "visa",
"reusable": true,
"signature": "SIG_uSYN4fv1adlAuoij8QXh",
"account_name": "BoJack Horseman"
},
"domain": "test",
"start": 1459296064,
"status": "active",
"quantity": 1,
"amount": 50000,
"subscription_code": "SUB_vsyqdmlzble3uii",
"email_token": "d7gofp6yppn3qz7",
"easy_cron_id": null,
"cron_expression": "0 0 28 * *",
"next_payment_date": "2016-04-28T07:00:00.000Z",
"open_invoice": null,
"id": 9,
"createdAt": "2016-03-30T00:01:04.000Z",
"updatedAt": "2016-03-30T00:22:58.000Z"
}
}{
"status": false,
"message": "An error occurred",
"meta": {
"nextStep": "string"
},
"type": "string",
"code": "validation_error",
"errorCodeMappingNotFound": true
}{
"status": false,
"message": "An error occurred",
"meta": {
"nextStep": "string"
},
"type": "string",
"code": "validation_error",
"errorCodeMappingNotFound": true
}Copy link Disable Subscription
Disable a subscription on your integration
Request Body
Subscription code
Email token
Response
200Subscription Disable response
POST
/subscription/disablecurl https://api.paystack.co/subscription/disable \
-H "Authorization: Bearer YOUR_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{
"code": "SUB_vsyqdmlzble3uii",
"token": "d7gofp6yppn3qz7"
}' \
-X POSTimport { Paystack } from "@paystack/paystack-sdk";
const paystack = new Paystack({ secretKey: process.env.PAYSTACK_SECRET_KEY! });
const response = await paystack.subscription.disable({
code: "SUB_vsyqdmlzble3uii",
token: "d7gofp6yppn3qz7"
});
console.log(response.data);require "paystack"
paystack = Paystack::Client.new(ENV.fetch("PAYSTACK_SECRET_KEY"))
response = paystack.subscription.disable({
code: "SUB_vsyqdmlzble3uii",
token: "d7gofp6yppn3qz7"
})
puts response.dataResponse
{
"status": true,
"message": "Subscription disabled successfully"
}{
"status": false,
"message": "An error occurred",
"meta": {
"nextStep": "string"
},
"type": "string",
"code": "validation_error",
"errorCodeMappingNotFound": true
}Copy link Enable Subscription
Enable a subscription on your integration
Request Body
Subscription code
Email token
Response
200Request successful
POST
/subscription/enablecurl https://api.paystack.co/subscription/enable \
-H "Authorization: Bearer YOUR_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{
"code": "SUB_vsyqdmlzble3uii",
"token": "d7gofp6yppn3qz7"
}' \
-X POSTimport { Paystack } from "@paystack/paystack-sdk";
const paystack = new Paystack({ secretKey: process.env.PAYSTACK_SECRET_KEY! });
const response = await paystack.subscription.enable({
code: "SUB_vsyqdmlzble3uii",
token: "d7gofp6yppn3qz7"
});
console.log(response.data);require "paystack"
paystack = Paystack::Client.new(ENV.fetch("PAYSTACK_SECRET_KEY"))
response = paystack.subscription.enable({
code: "SUB_vsyqdmlzble3uii",
token: "d7gofp6yppn3qz7"
})
puts response.dataResponse
{
"status": true,
"message": "Subscription enabled successfully"
}{
"status": false,
"message": "An error occurred",
"meta": {
"nextStep": "string"
},
"type": "string",
"code": "validation_error",
"errorCodeMappingNotFound": true
}Copy link Generate Update Subscription Link
Generate a link for updating the card on a subscription
Path Parameters
Subscription code
Response
200Request successful
GET
/subscription/{code}/manage/linkcurl https://api.paystack.co/subscription/qlgwhpyq1ts9nsw/manage/link \
-H "Authorization: Bearer YOUR_SECRET_KEY"import { Paystack } from "@paystack/paystack-sdk";
const paystack = new Paystack({ secretKey: process.env.PAYSTACK_SECRET_KEY! });
const response = await paystack.subscription.manageLink("qlgwhpyq1ts9nsw");
console.log(response.data);require "paystack"
paystack = Paystack::Client.new(ENV.fetch("PAYSTACK_SECRET_KEY"))
response = paystack.subscription.manage_link("qlgwhpyq1ts9nsw")
puts response.dataResponse
{
"status": true,
"message": "Link generated",
"data": {
"link": "https://paystack.com/manage/subscriptions/qlgwhpyq1ts9nsw?subscription_token=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWJzY3JpcHRpb25fY29kZSI6IlNVQl9xbGd3aHB5cTB0czluc3ciLCJpbnRlZ3JhdGlvbiI6MzUzNTE0LCJkb21haW4iOiJ0ZXN0IiwiZW1haWxfdG9rZW4iOiJzNXIwZjA0ODdwcnNtZWsiLCJpYXQiOjE2MzUyNTkxMzEsIm5iZiI6MTYzNTI1OTEzcjeR82XhwIjoxNjM1MzQ1NTMxfQ.FK1glvwMjHu9J8P-4n2oXPN_u_fIpQZ-F_s5x_4WLag"
}
}{
"status": false,
"message": "An error occurred",
"meta": {
"nextStep": "string"
},
"type": "string",
"code": "validation_error",
"errorCodeMappingNotFound": true
}Copy link Send Update Subscription Link
Email a customer a link for updating the card on their subscription
Path Parameters
Subscription code
Response
200Request successful
POST
/subscription/{code}/manage/emailcurl https://api.paystack.co/subscription/qlgwhpyq1ts9nsw/manage/email \
-H "Authorization: Bearer YOUR_SECRET_KEY" \
-H "Content-Type: application/json" \
-X POSTimport { Paystack } from "@paystack/paystack-sdk";
const paystack = new Paystack({ secretKey: process.env.PAYSTACK_SECRET_KEY! });
const response = await paystack.subscription.manageEmail("qlgwhpyq1ts9nsw");
console.log(response.data);require "paystack"
paystack = Paystack::Client.new(ENV.fetch("PAYSTACK_SECRET_KEY"))
response = paystack.subscription.manage_email("qlgwhpyq1ts9nsw")
puts response.dataResponse
{
"status": true,
"message": "Email successfully sent"
}{
"status": false,
"message": "An error occurred",
"meta": {
"nextStep": "string"
},
"type": "string",
"code": "validation_error",
"errorCodeMappingNotFound": true
}