API Docs
/
No Results Found
Plans

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.

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.
tags
array
Show Sub-Attributes arrow
tag_option_id
long
Id of the Tag Option
is_tag_mandatory
string
tag_name
string
tag_id
long
ID of the Tag
tag_option_name
string
custom_fields
array
Custom fields for a Plan.
Show Sub-Attributes arrow
customfield_id
string
is_active
string
show_in_all_pdf
string
value_formatted
string
data_type
string
index
integer
label
string
Label of the Custom Field
show_on_pdf
string
placeholder
string
value
string
Value of the Custom Field
recurring_price
double
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
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
Number of cycles this plan's subscription should run for. If billing_cycles=12, the subscription would expire after 12 cycles. If billing_cycles=-1, the subscription would run until it is cancelled. If interval=2, interval_unit=months and billing_cycles=12, the customer would be billed every 2 months and this would go on for 12 times.
product_type
string
VAT India GST only
Product type for India/UK Edition.
hsn_or_sac
string
India GST only
HSN or SAC code for Goods/Services plan
item_tax_preferences
array
India GST only
Tax preferenece for plan
Show Sub-Attributes arrow
tax_specification
string
Tax specification for the plan. It can be either inter or intra.
tax_name
string
Name of the tax to which subscription is associated.
tax_percentage
number
Percentage of tax applied to the plan/addon
tax_id
string
, default is no tax will be associated
Tax ID to which you would like to associate with this plan.
addons
array
List of addons that the plan is associated with. It holds the list of objects with addon_code and name as properties.
Show Sub-Attributes arrow
addon_code
string
The addon code of the addon which is associated with the plan .
name
The name of the addon.
status
string
Status of the plan. It can be either active or inactive .
pricing_scheme
string
Pricing type of the addon
unit_name
string
A name of your choice to refer to one unit of the addon.
price_brackets
array
Show Sub-Attributes arrow
start_quantity
integer
(Required) for “volume” and “tier” pricing schemes.
Lower limit of the addon range.
end_quantity
integer
(Required) for “volume”, “tier” and “package” pricing schemes.
Upper limit of the addon range.
price
double
Per unit cost of the addon for the selected range. For the “package” pricing scheme, this would be the price of the specified quantity of addons.
url
string
Unique url of the plan.
created_time
string
The time at which the plan was created.
updated_time
string
The time at which the plan details were last updated.

Example

{ "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", "tax_id": "903000000065300", "trial_period": 1, "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, "product_type": "goods", "hsn_or_sac": "74191010", "item_tax_preferences": [ { "tax_specification": "intra", "tax_name": "GST", "tax_percentage": 10, "tax_id": "903000000065300" } ], "addons": [ { "addon_code": "Email-basic", "name": "Monthly_Addon", "status": "active", "pricing_scheme": "unit", "unit_name": "Email", "price_brackets": [ { "start_quantity": 1, "end_quantity": 50, "price": 10 } ] } ], "url": "https://subscriptions.zoho.com/subscribe/3b884751f87f05e584c3952b6388e7f96a2bba0f6b0532177e00f0ba8db832fc/basic-monthly", "created_time": "2016-06-05T17:40:49-0700", "updated_time": "2016-06-05T24:40:49-0700" }

Create a plan

Create a new plan.
oauthscope : 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
Number of cycles this plan's subscription should run for. If billing_cycles=12, the subscription would expire after 12 cycles. If billing_cycles=-1, the subscription would run until it is cancelled. If interval=2, interval_unit=months and billing_cycles=12, the customer would be billed every 2 months and this would go on for 12 times.
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.
tags
array
Show Sub-Attributes arrow
tag_id
long
ID of the Tag
tag_option_id
long
Id of the Tag Option
custom_fields
array
Custom fields for a Plan.
Show Sub-Attributes arrow
label
string
Label of the Custom Field
value
string
Value of the Custom Field
product_id
string
(Required)
Product ID to which you want to associate this plan with.
product_type
string
VAT India GST only
Product type for India/UK Edition.
hsn_or_sac
string
India GST only
HSN or SAC code for Goods/Services plan
item_tax_preferences
array
India GST only
Tax preferenece for plan
Show Sub-Attributes arrow
tax_specification
string
Tax specification for the plan. It can be either inter or intra.
tax_name
string
Name of the tax to which subscription is associated.
tax_percentage
number
Percentage of tax applied to the plan/addon
tax_id
string
, default is no tax will be associated
Tax ID to which you would like to associate with this plan.
tax_id
string
, default is no tax will be associated
Tax ID to which you would like to associate with this plan.
is_taxable
string
Sales Tax GST only
Set to true if plan must be tax inclusive.
tax_exemption_id
string
Sales Tax GST only
Unique ID of the tax exemption.
tax_exemption_code
string
Sales Tax GST only
Unique code of the tax exemption.
description
string
Short description regarding the plan.
store_markup_description
string
Long Description regarding the plan.
can_charge_setup_fee_immediately
boolean
Set this value to "true", if you want to enable upfront setup fees charges while creating or updating subscriptions with this plan.

Request Example

Click to copy
$ curl https://subscriptions.zoho.com/api/v1/plans -X POST -H "X-com-zoho-subscriptions-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -d '{"field":"value","field":"value"}'

Body Parameters

Click to copy
{ "plan_code": "basic-monthly", "name": "Basic", "recurring_price": 400, "unit": "kg", "interval": 1, "interval_unit": "months", "billing_cycles": -1, "trial_period": 1, "setup_fee": 100, "setup_fee_account_id": "903000987009903", "tags": [ { "tag_id": "460000000054182", "tag_option_id": "460000000054280" } ], "custom_fields": [ { "label": "cfitem", "value": "Normal" } ], "product_id": "903000000045027", "product_type": "goods", "hsn_or_sac": "74191010", "item_tax_preferences": [ { "tax_specification": "intra", "tax_name": "GST", "tax_percentage": 10, "tax_id": "903000000065300" } ], "tax_id": "903000000065300", "is_taxable": true, "tax_exemption_id": "903000006345", "tax_exemption_code": "GST FREE", "description": "Basic monthly plan.", "store_markup_description": "Mailbox Storage-100GB | User & Docs Storage-500GB | User", "can_charge_setup_fee_immediately": true }

Response Example

{ "code": 0, "message": "The plan has been created.", "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", "tax_id": "903000000065300", "trial_period": 1, "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, "product_type": "goods", "hsn_or_sac": "74191010", "item_tax_preferences": [ { "tax_specification": "intra", "tax_name": "GST", "tax_percentage": 10, "tax_id": "903000000065300" } ], "addons": [ { "addon_code": "Email-basic", "name": "Monthly_Addon", "status": "active", "pricing_scheme": "unit", "unit_name": "Email", "price_brackets": [ { "start_quantity": 1, "end_quantity": 50, "price": 10 } ] } ], "url": "https://subscriptions.zoho.com/subscribe/3b884751f87f05e584c3952b6388e7f96a2bba0f6b0532177e00f0ba8db832fc/basic-monthly", "created_time": "2016-06-05T17:40:49-0700", "updated_time": "2016-06-05T24:40:49-0700" } }

List all plans

List of all plans created.
oauthscope : 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.

Request Example

Click to copy
$ curl https://subscriptions.zoho.com/api/v1/plans -H "X-com-zoho-subscriptions-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f"

Response Example

{ "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", "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.
oauthscope : 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
Number of cycles this plan's subscription should run for. If billing_cycles=12, the subscription would expire after 12 cycles. If billing_cycles=-1, the subscription would run until it is cancelled. If interval=2, interval_unit=months and billing_cycles=12, the customer would be billed every 2 months and this would go on for 12 times.
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.
tags
array
Show Sub-Attributes arrow
tag_id
long
ID of the Tag
tag_option_id
long
Id of the Tag Option
custom_fields
array
Custom fields for a Plan.
Show Sub-Attributes arrow
label
string
Label of the Custom Field
value
string
Value of the Custom Field
addons
array
List of addons that the plan is associated with. It holds the list of objects with addon_code and name as properties.
Show Sub-Attributes arrow
addon_code
string
The addon code of the addon which is associated with the plan .
name
(Required)
The name of the addon.
product_type
string
VAT India GST only
Product type for India/UK Edition.
hsn_or_sac
string
India GST only
HSN or SAC code for Goods/Services plan
item_tax_preferences
array
India GST only
Tax preferenece for plan
Show Sub-Attributes arrow
tax_specification
string
Tax specification for the plan. It can be either inter or intra.
tax_name
string
Name of the tax to which subscription is associated.
tax_percentage
number
Percentage of tax applied to the plan/addon
tax_id
string
, default is no tax will be associated
Tax ID to which you would like to associate with this plan.
tax_id
string
, default is no tax will be associated
Tax ID to which you would like to associate with this plan.
is_taxable
string
Sales Tax GST only
Set to true if plan must be tax inclusive.
tax_exemption_id
string
Sales Tax GST only
Unique ID of the tax exemption.
tax_exemption_code
string
Sales Tax GST only
Unique code of the tax exemption.
description
string
Short description regarding the plan.
store_markup_description
string
Long Description regarding the plan.
can_charge_setup_fee_immediately
boolean
Set this value to "true", if you want to enable upfront setup fees charges while creating or updating subscriptions with this plan.

Request Example

Click to copy
$ curl https://subscriptions.zoho.com/api/v1/plans/{plan_code} -X PUT -H "X-com-zoho-subscriptions-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f" -d '{"field":"value","field":"value"}'

Body Parameters

Click to copy
{ "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": "903000987009905", "tags": [ { "tag_id": "460000000054182", "tag_option_id": "460000000054278" } ], "custom_fields": [ { "label": "cfitem", "value": "test" } ], "addons": [ { "addon_code": "Email-basic", "name": "Monthly_Addon" } ], "product_type": "goods", "hsn_or_sac": "74191010", "item_tax_preferences": [ { "tax_specification": "intra", "tax_name": "GST", "tax_percentage": 10, "tax_id": "903000000065300" } ], "tax_id": "903000000065300", "is_taxable": true, "tax_exemption_id": "903000006345", "tax_exemption_code": "GST FREE", "description": "Basic monthly plan.", "store_markup_description": "Mailbox Storage-100GB | User & Docs Storage-500GB | User", "can_charge_setup_fee_immediately": true }

Response Example

{ "code": 0, "message": "The plan details has been updated.", "plan": { "plan_code": "basic-monthly", "name": "Basic", "description": "Basic monthly plan.", "store_markup_description": "Mailbox Storage-100GB | User & Docs Storage-500GB | User", "can_charge_setup_fee_immediately": true, "status": "active", "product_id": "903000000045027", "account_id": "903000987009900", "account_name": "Sales", "trial_period": 0, "setup_fee": 0, "setup_fee_account_id": "903000987009905", "setup_fee_account_name": "Sales", "tags": [ { "tag_option_id": "460000000054278", "is_tag_mandatory": false, "tag_name": "Colors", "tag_id": "460000000054182", "tag_option_name": "Green" } ], "custom_fields": [ { "customfield_id": "2000000029001", "is_active": "true", "show_in_all_pdf": "true", "value_formatted": "test", "data_type": "string", "index": 1, "label": "cfitem", "show_on_pdf": false, "placeholder": "cf_cfitem", "value": "test" } ], "recurring_price": 400, "unit": "kg", "interval": 1, "interval_unit": "months", "billing_cycles": -1, "url": "https://subscriptions.zoho.com/subscribe/3b884751f87f05e584c3952b6388e7f96a2bba0f6b0532177e00f0ba8db832fc/basic-monthly", "tax_id": "903000000065300", "product_type": "goods", "hsn_or_sac": "74191010", "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" } }

Retrieve a plan

Retrieve details of an existing plan.
oauthscope : ZohoSubscriptions.plans.READ

Request Example

Click to copy
$ curl https://subscriptions.zoho.com/api/v1/plans/{plan_code} -H "X-com-zoho-subscriptions-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f"

Response Example

{ "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://subscriptions.zoho.com/subscribe/3b884751f87f05e584c3952b6388e7f96a2bba0f6b0532177e00f0ba8db832fc/basic-monthly", "tax_id": "903000000065300", "product_type": "goods", "hsn_or_sac": "74191010", "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.
oauthscope : ZohoSubscriptions.plans.DELETE

Request Example

Click to copy
$ curl https://subscriptions.zoho.com/api/v1/plans/{plan_code} -X DELETE -H "X-com-zoho-subscriptions-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f"

Response Example

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

Mark as active

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

Request Example

Click to copy
$ curl https://subscriptions.zoho.com/api/v1/plans/{plan_code}/markasactive -X POST -H "X-com-zoho-subscriptions-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f"

Response Example

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

Mark as inactive

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

Request Example

Click to copy
$ curl https://subscriptions.zoho.com/api/v1/plans/{plan_code}/markasinactive -X POST -H "X-com-zoho-subscriptions-organizationid: 10234695" -H "Authorization: Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f"

Response Example

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