Subscriptions

This section discusses all API endpoints that are critical for managing user subscriptions. With these APIs, You can query your existing subscriptions, as well as activate or deactivate a user's subscription.

Get all Subscriptions

This endpoint allows the developers to query all subscribers (cancelled subscriber included). You can do a single or bulk query with the endpoint depending on your use case.

get https://api.flutterwave.com/v3/subscriptions

Query Params

email string

This is the email of the subscriber. You can use this to query the transactions for a single customer.

transaction_id int32

This is a unique transaction identifier generated by our systems. It is returned in the initiate charge response as data.id.

plan int32

This is the ID of the payment plan. It is returned in the call to create a payment plan as data.id.

subscribed_from string

This is the start date of the subscriptions(when they are first active). You can use this as a starting point for your query. The expected date format for this parameter is YYYY-MM-DD

subscribed_to string

This is the end date for a subscription. Like subscribed_from, It also has an expected date format of YYYY-MM-DD.

next_due_from string

This is the parameter to filter from the start date of the next due subscriptions.

next_due_to string

This is the parameter to filter to the end date of the next due subscriptions.

page string

This is the page number to retrieve e.g. setting 1 retrieves the first page.

status string

This is the status for the queried transactions. Expected values are active and cancelled.

Headers

Authorization string

Pass your secret key as a bearer token in the request header to authorize this call. Unauthorized calls would return a 401 http code or raise unauthorized error in the different SDKs.

const Flutterwave = require('flutterwave-node-v3');
const flw = new Flutterwave("public key", "secret key");

// to return every subscription
const response = await flw.Subscription.fetch_all();

// to return a single subscription
const payload = {"email": "developers@flutterwavego.com"};
const response = await flw.Subscription.get();
require("Flutterwave-PHP-v3/library/Transactions.php");
use Flutterwave\Subscription;
$subscription = new Subscription();
$resultGet = $subscription->getAllSubscription();
print_r($resultGet);
require './flutterwave_sdk'
payment = Flutterwave.new("public key", "secret key", "encryption key")
subscription = Subscriptions.new(payment)
response = subscription.get_all_subscriptions
print response
{
  "status": "success",
  "message": "Plan subscriptions fetched",
  "meta": {
    "page_info": {
      "total": 2,
      "current_page": 1,
      "total_pages": 1
    }
  },
  "data": [
    {
      "id": 4147,
      "amount": 2000,
      "customer": {
        "id": 247546,
        "customer_email": "developers@flutterwavego.com"
      },
      "plan": 3657,
      "status": "cancelled",
      "created_at": "2019-12-31T17:00:55.000Z"
    },
    {
      "id": 4146,
      "amount": 2000,
      "customer": {
        "id": 247490,
        "customer_email": "developers@flutterwavego.com"
      },
      "plan": 3657,
      "status": "cancelled",
      "created_at": "2019-12-31T14:44:20.000Z"
    }
  ]
}

{}

Activate a Subscription

This section describes how to activate a previously cancelled subscription.

put https://api.flutterwave.com/v3/subscriptions/:id/activate

Path Params

id int32

This is the ID of the subscription you want to activate. It is returned in the call to query all subscription as data.id.

Headers

Authorization string

Pass your secret key as a bearer token in the request header to authorize this call. Unauthorized calls would return a 401 http code or raise unauthorized error in the different SDKs.

const Flutterwave = require('flutterwave-node-v3');
const flw = new Flutterwave("public key", "secret key");
const payload = {"id":"4147"};
const response = await flw.Subscription.activate(payload);
require("Flutterwave-PHP-v3/library/Transactions.php");
use Flutterwave\Subscription;
$id = 4147;
$subscription = new Subscription();
$resultActivate = $subscription->activateSubscription($id);
print_r($resultActivate);
require './flutterwave_sdk'
payment = Flutterwave.new("public key", "secret key", "encryption key")
subscription = Subscriptions.new(payment)
response = subscription.activate_subscription(4147)
print response
{
  "status": "success",
  "message": "Subscription activated",
  "data": {
    "id": 4147,
    "amount": 2000,
    "customer": {
      "id": 247546,
      "customer_email": "developers@flutterwavego.com"
    },
    "plan": 3657,
    "status": "active",
    "created_at": "2019-12-31T17:00:55.000Z"
  }
}

{}

Deactivate a Subscription

This section describes how to deactivate an active subscription.

put https://api.flutterwave.com/v3/subscriptions/:id/cancel

Path Params

id int32

This is the ID of the subscription to be cancelled. It is returned in the call to query all subscription as data.id.

Headers

Authorization string

Pass your secret key as a bearer token in the request header to authorize this call. Unauthorized calls would return a 401 http code or raise unauthorized error in the different SDKs.

const Flutterwave = require('flutterwave-node-v3');
const flw = new Flutterwave("public key", "secret key");
const payload = {"id":"4147"};
const response = await flw.Subscription.cancel(payload)
require("Flutterwave-PHP-v3/library/Transactions.php");
use Flutterwave\Subscription;
$id = 4147;
$subscription = new Subscription();
$resultCancel = $subscription->cancelSubscription($id);
print_r($resultCancel);
require './flutterwave_sdk'
payment = Flutterwave.new("public key", "secret key", "encryption key")
subscription = Subscriptions.new(payment)
response = subscription.cancel_subscription(4147)
print response
{
  "status": "success",
  "message": "Subscription cancelled",
  "data": {
    "id": 4147,
    "amount": 2000,
    "customer": {
      "id": 247546,
      "customer_email": "developers@flutterwavego.com"
    },
    "plan": 3657,
    "status": "cancelled",
    "created_at": "2019-12-31T17:00:55.000Z"
  }
}

{}
Loading...