Copy link List Subscriptions

List all subscriptions available on your integration

Query Parameters

perPageinteger
Number of records to fetch per page
pageinteger
The section to retrieve
planinteger
Plan ID
customerstring
Customer ID
fromstring
The start date
tostring
The end date

Response

200Subscription List response
statusrequiredboolean
messagerequiredstring
datarequiredarray[object]
metarequiredobject
5 object properties
totalrequiredinteger
skippedrequiredinteger
perPagerequiredinteger
pagerequiredinteger
pageCountrequiredinteger
GET/subscription
curl 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.data
Response
{
  "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

customerrequiredstring
Customer's email address or customer code
planrequiredstring
Plan code
authorizationstring
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
start_datestringdate-time
Set the date for the first debit. (ISO 8601 format) e.g. 2017-05-16T00:30:13+01:00

Response

200Subscription Create response
statusrequiredboolean
messagerequiredstring
datarequiredobject
22 object properties
customerrequiredinteger
planrequiredinteger
integrationrequiredinteger
domainrequiredstring
startrequiredinteger
statusrequiredstring
quantityrequiredinteger
amountrequiredinteger
authorizationrequiredinteger
invoice_limitrequiredinteger
split_coderequiredstring
subscription_coderequiredstring
email_tokenrequiredstring
idrequiredinteger
cancelledAtrequiredstring
createdAtrequiredstring
updatedAtrequiredstring
cron_expressionrequiredstring
next_payment_daterequiredstring
easy_cron_idrequiredstring
open_invoicerequiredstring
metadatarequiredobject
POST/subscription
curl https://api.paystack.co/subscription \
  -H "Authorization: Bearer YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customer": "CUS_xnxdt6s1zg1f4nx",
    "plan": "PLN_gx2wn530m0i3w3m"
  }' \
  -X POST
import { 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.data
Response
{
  "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

coderequiredstring
The subscription code for the subscription you want to fetch

Response

200Subscription Fetch response
statusrequiredboolean
messagerequiredstring
datarequiredobject
22 object properties
idrequiredinteger
domainrequiredstring
statusrequiredstring
subscription_coderequiredstring
email_tokenrequiredstring
amountrequiredinteger
cron_expressionrequiredstring
next_payment_daterequiredstring
open_invoicerequiredstring
createdAtrequiredstring
cancelledAtrequiredstring
integrationrequiredinteger
planrequiredobject
9 object properties
idrequiredinteger
namerequiredstring
plan_coderequiredstring
descriptionrequiredstring
amountrequiredinteger
intervalrequiredstring
send_invoicesrequiredboolean
send_smsrequiredboolean
currencyrequiredstring
authorizationrequiredobject
13 object properties
authorization_coderequiredstring
binrequiredstring
last4requiredstring
exp_monthrequiredstring
exp_yearrequiredstring
channelrequiredstring
card_typerequiredstring
bankrequiredstring
country_coderequiredstring
brandrequiredstring
reusablerequiredboolean
signaturerequiredstring
account_namerequiredstring
customerrequiredobject
9 object properties
idrequiredinteger
first_namerequiredstring
last_namerequiredstring
emailrequiredstring
customer_coderequiredstring
phonerequiredstring
metadatarequiredobject
risk_actionrequiredstring
international_format_phonerequiredstring
invoicesrequiredarray[object]
invoices_historyrequiredarray[object]
invoice_limitrequiredinteger
split_coderequiredstring
most_recent_invoicerequiredstring
payments_countrequiredinteger
metadatarequiredobject
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.data
Response
{
  "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

coderequiredstring
Subscription code
tokenrequiredstring
Email token

Response

200Subscription Disable response
statusrequiredboolean
messagerequiredstring
POST/subscription/disable
curl https://api.paystack.co/subscription/disable \
  -H "Authorization: Bearer YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "SUB_vsyqdmlzble3uii",
    "token": "d7gofp6yppn3qz7"
  }' \
  -X POST
import { 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.data
Response
{
  "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

coderequiredstring
Subscription code
tokenrequiredstring
Email token

Response

200Request successful
statusboolean
messagestring
dataobject
POST/subscription/enable
curl https://api.paystack.co/subscription/enable \
  -H "Authorization: Bearer YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "SUB_vsyqdmlzble3uii",
    "token": "d7gofp6yppn3qz7"
  }' \
  -X POST
import { 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.data
Response
{
  "status": true,
  "message": "Subscription enabled successfully"
}
{
  "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

coderequiredstring
Subscription code

Response

200Request successful
statusboolean
messagestring
dataobject
POST/subscription/{code}/manage/email
curl https://api.paystack.co/subscription/qlgwhpyq1ts9nsw/manage/email \
  -H "Authorization: Bearer YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -X POST
import { 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.data
Response
{
  "status": true,
  "message": "Email successfully sent"
}
{
  "status": false,
  "message": "An error occurred",
  "meta": {
    "nextStep": "string"
  },
  "type": "string",
  "code": "validation_error",
  "errorCodeMappingNotFound": true
}