Plans

A plan object contains the billing and pricing information of a plan. Your organization may consist of plans that differ either by features or by the plan’s billing frequency. You can have a $10 basic plan, $20 professional plan, $24 monthly or a $240 yearly plan.

End Points

POST

/plans

/plans/{plan_code}/markasactive

POST

/plans/{plan_code}/markasinactive

Attribute

plan_code

string

Unique string of your choice which lets you identify this plan.

name

string

Name of your choice to be displayed in the interface and invoices.

description

string

Short description regarding the plan.

store_markup_description

string

Long Description regarding the plan.

status

string

Status of the plan. It can be either active or inactive .

product_id

string

Product ID to which you want to associate this plan with.

account_id

string

Account ID which the plan is associated.

account_name

string

Account name which the plan is associated.

tax_id

string

, default is no tax will be associated

Tax ID to which you would like to associate with this plan.

trial_period

integer

, default is 0

Number of free trial days that can be granted when a customer is subscribed to this plan.

setup_fee

double

, default is 0

This indicates a one-time fee charged upfront while creating a subscription for this plan.

setup_fee_account_id

string

Setup Fee Account ID which the setup fee of the plan is associated.

setup_fee_account_name

string

Setup Fee Account Name which the setup fee of the plan is associated.

Create a plan

Create a new plan.
OAuth Scope : ZohoSubscriptions.plans.CREATE

Arguments

plan_code

string

(Required)

Unique string of your choice which lets you identify this plan.

name

string

(Required)

Name of your choice to be displayed in the interface and invoices.

recurring_price

double

(Required)

The customer is charged an amount over an interval for the subscription.

unit

string

A name of your choice to refer to one unit of the plan.

interval

integer

(Required)

Indicates the number of intervals between each billing. If interval=2, the customer would be billed every two months or years depending on the value for interval_unit.

interval_unit

string

, default is months

The values can be either months or years. For interval=2 and interval_unit=months, the customer is billed every two months.

billing_cycles

integer

, default is -1

trial_period

integer

, default is 0

Number of free trial days that can be granted when a customer is subscribed to this plan.

setup_fee

double

, default is 0

This indicates a one-time fee charged upfront while creating a subscription for this plan.

setup_fee_account_id

string

Setup Fee Account ID which the setup fee of the plan is associated.

List all plans

List of all plans created.
OAuth Scope : ZohoSubscriptions.plans.READ

Query Parameters

filter_by

To list plans based on the Status, use the parameter filter_by. The allowed values for filter_by are PlanStatus.(All, ACTIVE and INACTIVE).

product_id

To list plans of a particular product use the parameter product_id.

headers_data = Map();
headers_data.put("X-com-zoho-subscriptions-organizationid", "10234695");
headers_data.put("Authorization", "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f");
response = invokeUrl
[
url: "https://www.zohoapis.com/billing/v1/plans"
type: GET
headers: headers_data
connection: <connection_name>
]
info response;

OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://www.zohoapis.com/billing/v1/plans")
  .get()
  .addHeader("X-com-zoho-subscriptions-organizationid", "10234695")
  .addHeader("Authorization", "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f")
  .build();

Response response = client.newCall(request).execute();

const options = {
  method: 'GET',
  headers: {
    'X-com-zoho-subscriptions-organizationid': '10234695',
    Authorization: 'Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f'
  }
};

fetch('https://www.zohoapis.com/billing/v1/plans', options)
  .then(response => response.json())
  .then(response => console.log(response))
  .catch(err => console.error(err));

import http.client

conn = http.client.HTTPSConnection("www.zohoapis.com")

headers = {
    'X-com-zoho-subscriptions-organizationid': "10234695",
    'Authorization': "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f"
    }

conn.request("GET", "/billing/v1/plans", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

const http = require("https");

const options = {
  "method": "GET",
  "hostname": "www.zohoapis.com",
  "port": null,
  "path": "/billing/v1/plans",
  "headers": {
    "X-com-zoho-subscriptions-organizationid": "10234695",
    "Authorization": "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f"
  }
};

const req = http.request(options, function (res) {
  const chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function () {
    const body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.end();

curl --request GET \
  --url https://www.zohoapis.com/billing/v1/plans \
  --header 'Authorization: Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f' \
  --header 'X-com-zoho-subscriptions-organizationid: 10234695'

{
    "code": 0,
    "message": "success",
    "plans": [
        {
            "plan_code": "basic-monthly",
            "name": "Basic",
            "recurring_price": 400,
            "unit": "kg",
            "interval": 1,
            "interval_unit": "months",
            "billing_cycles": -1,
            "trial_period": 0,
            "setup_fee": 0,
            "setup_fee_account_id": "903000987009903",
            "setup_fee_account_name": "General Income",
            "product_id": "903000000045027",
            "tax_id": "903000000065300",
            "product_type": "goods",
            "hsn_or_sac": "74191010",
            "sat_item_key_code": 71121206,
            "unitkey_code": "E48",
            "item_tax_preferences": [
                {
                    "tax_specification": "intra",
                    "tax_name": "GST",
                    "tax_percentage": 10,
                    "tax_id": "903000000065300"
                }
            ],
            "description": "Basic monthly plan.",
            "store_markup_description": "Mailbox Storage-100GB | User & Docs Storage-500GB | User",
            "status": "active",
            "addons": [
                {
                    "addon_code": "Email-basic",
                    "name": "Basic"
                }
            ],
            "created_time": "2016-06-05T17:40:49-0700",
            "updated_time": "2016-06-05T24:40:49-0700"
        },
        {...},
        {...}
    ]
}

Update a plan

Update details of an existing plan.
OAuth Scope : ZohoSubscriptions.plans.UPDATE

Arguments

plan_code

string

(Required)

Unique string of your choice which lets you identify this plan.

name

string

(Required)

Name of your choice to be displayed in the interface and invoices.

recurring_price

double

(Required)

The customer is charged an amount over an interval for the subscription.

unit

string

A name of your choice to refer to one unit of the plan.

interval

integer

(Required)

Indicates the number of intervals between each billing. If interval=2, the customer would be billed every two months or years depending on the value for interval_unit.

interval_unit

string

, default is months

The values can be either months or years. For interval=2 and interval_unit=months, the customer is billed every two months.

billing_cycles

integer

, default is -1

trial_period

integer

, default is 0

Number of free trial days that can be granted when a customer is subscribed to this plan.

setup_fee

double

, default is 0

This indicates a one-time fee charged upfront while creating a subscription for this plan.

setup_fee_account_id

string

Setup Fee Account ID which the setup fee of the plan is associated.

Retrieve a plan

Retrieve details of an existing plan.
OAuth Scope : ZohoSubscriptions.plans.READ

headers_data = Map();
headers_data.put("X-com-zoho-subscriptions-organizationid", "10234695");
headers_data.put("Authorization", "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f");
response = invokeUrl
[
url: "https://www.zohoapis.com/billing/v1/plans/basic-monthly"
type: GET
headers: headers_data
connection: <connection_name>
]
info response;

OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://www.zohoapis.com/billing/v1/plans/basic-monthly")
  .get()
  .addHeader("X-com-zoho-subscriptions-organizationid", "10234695")
  .addHeader("Authorization", "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f")
  .build();

Response response = client.newCall(request).execute();

const options = {
  method: 'GET',
  headers: {
    'X-com-zoho-subscriptions-organizationid': '10234695',
    Authorization: 'Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f'
  }
};

fetch('https://www.zohoapis.com/billing/v1/plans/basic-monthly', options)
  .then(response => response.json())
  .then(response => console.log(response))
  .catch(err => console.error(err));

import http.client

conn = http.client.HTTPSConnection("www.zohoapis.com")

headers = {
    'X-com-zoho-subscriptions-organizationid': "10234695",
    'Authorization': "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f"
    }

conn.request("GET", "/billing/v1/plans/basic-monthly", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

const http = require("https");

const options = {
  "method": "GET",
  "hostname": "www.zohoapis.com",
  "port": null,
  "path": "/billing/v1/plans/basic-monthly",
  "headers": {
    "X-com-zoho-subscriptions-organizationid": "10234695",
    "Authorization": "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f"
  }
};

const req = http.request(options, function (res) {
  const chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function () {
    const body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.end();

curl --request GET \
  --url https://www.zohoapis.com/billing/v1/plans/basic-monthly \
  --header 'Authorization: Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f' \
  --header 'X-com-zoho-subscriptions-organizationid: 10234695'

{
    "code": 0,
    "message": "success",
    "plan": {
        "plan_code": "basic-monthly",
        "name": "Basic",
        "description": "Basic monthly plan.",
        "store_markup_description": "Mailbox Storage-100GB | User & Docs Storage-500GB | User",
        "status": "active",
        "product_id": "903000000045027",
        "account_id": "903000987009900",
        "account_name": "Sales",
        "trial_period": 0,
        "setup_fee": 0,
        "setup_fee_account_id": "903000987009903",
        "setup_fee_account_name": "General Income",
        "tags": [
            {
                "tag_option_id": "460000000054280",
                "is_tag_mandatory": false,
                "tag_name": "Colors",
                "tag_id": "460000000054182",
                "tag_option_name": "Black"
            }
        ],
        "custom_fields": [
            {
                "customfield_id": "2000000029001",
                "is_active": "true",
                "show_in_all_pdf": "true",
                "value_formatted": "Normal",
                "data_type": "string",
                "index": 1,
                "label": "cfitem",
                "show_on_pdf": false,
                "placeholder": "cf_cfitem",
                "value": "Normal"
            }
        ],
        "recurring_price": 400,
        "unit": "kg",
        "interval": 1,
        "interval_unit": "months",
        "billing_cycles": -1,
        "url": "https://billing.zoho.com/subscribe/3b884751f87f05e584c3952b6388e7f96a2bba0f6b0532177e00f0ba8db832fc/basic-monthly",
        "tax_id": "903000000065300",
        "product_type": "goods",
        "hsn_or_sac": "74191010",
        "sat_item_key_code": 71121206,
        "unitkey_code": "E48",
        "item_tax_preferences": [
            {
                "tax_specification": "intra",
                "tax_name": "GST",
                "tax_percentage": 10,
                "tax_id": "903000000065300"
            }
        ],
        "created_time": "2016-06-05T17:40:49-0700",
        "updated_time": "2016-06-05T24:40:49-0700"
    }
}

Delete a plan

Delete an existing plan. A plan can only be deleted if it has no transactions associated with it.
OAuth Scope : ZohoSubscriptions.plans.DELETE

headers_data = Map();
headers_data.put("X-com-zoho-subscriptions-organizationid", "10234695");
headers_data.put("Authorization", "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f");
response = invokeUrl
[
url: "https://www.zohoapis.com/billing/v1/plans/basic-monthly"
type: DELETE
headers: headers_data
connection: <connection_name>
]
info response;

OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://www.zohoapis.com/billing/v1/plans/basic-monthly")
  .delete(null)
  .addHeader("X-com-zoho-subscriptions-organizationid", "10234695")
  .addHeader("Authorization", "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f")
  .build();

Response response = client.newCall(request).execute();

const options = {
  method: 'DELETE',
  headers: {
    'X-com-zoho-subscriptions-organizationid': '10234695',
    Authorization: 'Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f'
  }
};

fetch('https://www.zohoapis.com/billing/v1/plans/basic-monthly', options)
  .then(response => response.json())
  .then(response => console.log(response))
  .catch(err => console.error(err));

import http.client

conn = http.client.HTTPSConnection("www.zohoapis.com")

headers = {
    'X-com-zoho-subscriptions-organizationid': "10234695",
    'Authorization': "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f"
    }

conn.request("DELETE", "/billing/v1/plans/basic-monthly", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

const http = require("https");

const options = {
  "method": "DELETE",
  "hostname": "www.zohoapis.com",
  "port": null,
  "path": "/billing/v1/plans/basic-monthly",
  "headers": {
    "X-com-zoho-subscriptions-organizationid": "10234695",
    "Authorization": "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f"
  }
};

const req = http.request(options, function (res) {
  const chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function () {
    const body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.end();

curl --request DELETE \
  --url https://www.zohoapis.com/billing/v1/plans/basic-monthly \
  --header 'Authorization: Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f' \
  --header 'X-com-zoho-subscriptions-organizationid: 10234695'

{
    "code": 0,
    "message": "The plan has been deleted."
}

Mark as active

Change the status of the plan to active.
OAuth Scope : ZohoSubscriptions.plans.CREATE

headers_data = Map();
headers_data.put("X-com-zoho-subscriptions-organizationid", "10234695");
headers_data.put("Authorization", "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f");
response = invokeUrl
[
url: "https://www.zohoapis.com/billing/v1/plans/basic-monthly/markasactive"
type: POST
headers: headers_data
connection: <connection_name>
]
info response;

OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://www.zohoapis.com/billing/v1/plans/basic-monthly/markasactive")
  .post(null)
  .addHeader("X-com-zoho-subscriptions-organizationid", "10234695")
  .addHeader("Authorization", "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f")
  .build();

Response response = client.newCall(request).execute();

const options = {
  method: 'POST',
  headers: {
    'X-com-zoho-subscriptions-organizationid': '10234695',
    Authorization: 'Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f'
  }
};

fetch('https://www.zohoapis.com/billing/v1/plans/basic-monthly/markasactive', options)
  .then(response => response.json())
  .then(response => console.log(response))
  .catch(err => console.error(err));

import http.client

conn = http.client.HTTPSConnection("www.zohoapis.com")

headers = {
    'X-com-zoho-subscriptions-organizationid': "10234695",
    'Authorization': "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f"
    }

conn.request("POST", "/billing/v1/plans/basic-monthly/markasactive", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

const http = require("https");

const options = {
  "method": "POST",
  "hostname": "www.zohoapis.com",
  "port": null,
  "path": "/billing/v1/plans/basic-monthly/markasactive",
  "headers": {
    "X-com-zoho-subscriptions-organizationid": "10234695",
    "Authorization": "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f"
  }
};

const req = http.request(options, function (res) {
  const chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function () {
    const body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.end();

curl --request POST \
  --url https://www.zohoapis.com/billing/v1/plans/basic-monthly/markasactive \
  --header 'Authorization: Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f' \
  --header 'X-com-zoho-subscriptions-organizationid: 10234695'

{
    "code": 0,
    "message": "The plan has been marked as active."
}

Mark as inactive

Change the status of the plan to inactive.
OAuth Scope : ZohoSubscriptions.plans.CREATE

headers_data = Map();
headers_data.put("X-com-zoho-subscriptions-organizationid", "10234695");
headers_data.put("Authorization", "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f");
response = invokeUrl
[
url: "https://www.zohoapis.com/billing/v1/plans/basic-monthly/markasinactive"
type: POST
headers: headers_data
connection: <connection_name>
]
info response;

OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://www.zohoapis.com/billing/v1/plans/basic-monthly/markasinactive")
  .post(null)
  .addHeader("X-com-zoho-subscriptions-organizationid", "10234695")
  .addHeader("Authorization", "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f")
  .build();

Response response = client.newCall(request).execute();

const options = {
  method: 'POST',
  headers: {
    'X-com-zoho-subscriptions-organizationid': '10234695',
    Authorization: 'Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f'
  }
};

fetch('https://www.zohoapis.com/billing/v1/plans/basic-monthly/markasinactive', options)
  .then(response => response.json())
  .then(response => console.log(response))
  .catch(err => console.error(err));

import http.client

conn = http.client.HTTPSConnection("www.zohoapis.com")

headers = {
    'X-com-zoho-subscriptions-organizationid': "10234695",
    'Authorization': "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f"
    }

conn.request("POST", "/billing/v1/plans/basic-monthly/markasinactive", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

const http = require("https");

const options = {
  "method": "POST",
  "hostname": "www.zohoapis.com",
  "port": null,
  "path": "/billing/v1/plans/basic-monthly/markasinactive",
  "headers": {
    "X-com-zoho-subscriptions-organizationid": "10234695",
    "Authorization": "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f"
  }
};

const req = http.request(options, function (res) {
  const chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function () {
    const body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.end();

curl --request POST \
  --url https://www.zohoapis.com/billing/v1/plans/basic-monthly/markasinactive \
  --header 'Authorization: Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f' \
  --header 'X-com-zoho-subscriptions-organizationid: 10234695'

{
    "code": 0,
    "message": "The plan has been marked as inactive."
}