Introduction

API Root Endpoint

https://subscriptions.zoho.com/api/v1

The Zoho Subscriptions API allows you to perform all the operations that you do with our web client.

Zoho Subscriptions API is built using REST principles which ensures predictable URLs that makes writing applications easy. This API follows HTTP rules, enabling a wide range of HTTP clients can be used to interact with the API.

Every resource is exposed as a URL. The URL of each resource can be obtained by accessing the API Root Endpoint.

In Zoho Subscriptions, your business is termed as an organization. If you have multiple businesses, you simply set each of those up as an individual organization. Each organization is an independent Zoho Subscriptions Organization with it’s own organization ID, base currency, time zone, language, customers, reports, etc.

The header X-com-zoho-subscriptions-organizationid along with the organization ID should be sent in with every API request to identify the organization.

The organization_id can be obtained from the GET /organizations API’s JSON response. Alternatively, it can be obtained from the Manage Organizations page in the admin console:

Login to the Zoho Subscriptions admin console. Click the drop down with organization’s name as the label and click Manage Organizations.

Now you’ll be able to find Organization IDs for each of your organizations.

Zoho Subscriptions uses HTTP status codes to indicate success or failure of an API call. In general, status codes in the 2xx range means success, 4xx range means there was an error in the provided information, and those in the 5xx range indicates server side errors. Commonly used HTTP status codes are listed below.

HTTP Status Codes

Status Code

Descriptions

2xx

Success

4xx

Bad request sent to server

5xx

Server side error

Status Code

Description

200

SuccessThe request was successfully completed.

201

CreatedThe request was a success and one or more resources have been created.

400

Bad requestThe request cannot be performed. Usually because of malformed parameter or missing parameter.

401

Unauthorized (Invalid AuthToken)Request was rejected because of invalid AuthToken.

403

ForbiddenThe user does not have enough permission or possibly not an user of the respective organization to access the resource.

404

URL Not FoundThe URL you’ve sent is wrong. It’s possible that the resource you’ve requested has been moved to another URL.

405

Method Not AllowedThe requested resource does not support the HTTP method used. For example, requesting List of all customers API with PUT as the HTTP method.

406

Not AcceptableThe requested response type is not supported by the client.

429

Too many requestsToo many requests within a certain time frame. To know more about api call limits, click here.

500

Server errorZoho Subscriptions' server encountered an error which prevents it from fulfilling the request. Although this rarely happens, we recommend you to contact us at support@zohosubscripitons.com if you receive this error.

Zoho Subscriptions provides APIs to retrieve lists of customers, plans and other resources - paginated to 200 items by default. The pagination information will be included in the list API response under the node name page_context.

By default first page will be listed. For navigating through pages, use the page parameter.

The per_page parameter can be used to set the number of records that you want to receive in the response.

API Call Limit

API calls are limited to provide better quality of service and availability to all the users. The limits on total calls are illustrated below:

BASIC Plan - 2500 API calls/day

STANDARD Plan - 10000 API calls/day

PROFESSIONAL Plan - 50000 API calls/day

Test Organization - 1000 API calls/day

API Collection

To try out our API, you can use the Postman, a REST client. You can download our API collection and give it a swing. Just click the button below.

After importing the collection, you have to configure the environment. You can either do it manualy or simply import our sample environment file and follow the steps given below.

In the Postman app, click the settings icon (cog icon) on the top-right and go to Manage Environment

Click the Import button and upload this updated sample file and complete the process

Products

A product refers to the service you offer your customers. There can be multiple products created if you offer more than one service. Each product can have different plans and addons associated with it.

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.

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

setup_fee

double

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

recurring_price

double

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

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

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

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.

ARGUMENTS

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

unit

Optional

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

interval

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

Optional , 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

Optional , 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

Optional

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

setup_fee

Optional

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

ARGUMENTS

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

unit

Optional

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

interval

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

Optional , 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

Optional , 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

Optional

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

setup_fee

Optional

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

List all plans

List of all plans created. To list plans of a particular product use the parameter product_id. To list plans based on the Status, use the parameter filter_by. The allowed values for filter_by are PlanStatus.(All, ACTIVE and INACTIVE).

Addons

An addon contains additional features that are not part of the subscribed plan, but are made available to customers on purchase of the addon. There are two kinds of addons - one-time and recurring. For a one-time addon, customers pay only once at the time of subscription, whereas for a recurring addon, customers have to pay for the addon each time they pay for the plan’s subscription. An addon can be associated with one or more plans of a product.

List of plans that the addon needs to be associated with. If an addon is to be associated with only two plans - "basic" and "professional", then applicable_to_all_plans is set to false. Only the plan codes of the plans that need to be associated with are required.

List of plans that the addon needs to be associated with. If an addon is to be associated with only two plans - "basic" and "professional", then applicable_to_all_plans is set to false. Only the plan codes of the plans that need to be associated with are required.

List of plans that the addon needs to be associated with. If an addon is to be associated with only two plans - "basic" and "professional", then applicable_to_all_plans is set to false. Only the plan codes of the plans that need to be associated with are required.

List of plans that the addon needs to be associated with. If an addon is to be associated with only two plans - "basic" and "professional", then applicable_to_all_plans is set to false. Only the plan codes of the plans that need to be associated with are required.

List of plans that the addon needs to be associated with. If an addon is to be associated with only two plans - "basic" and "professional", then applicable_to_all_plans is set to false. Only the plan codes of the plans that need to be associated with are required.

List of plans that the addon needs to be associated with. If an addon is to be associated with only two plans - "basic" and "professional", then applicable_to_all_plans is set to false. Only the plan codes of the plans that need to be associated with are required.

List all addons

List of all addons. To list addons of a particular product use the parameter product_id. To list addons of a particular plan use the parameter plan_code. To list plans based on the Status, use the parameter filter_by. The allowed values for filter_by are AddonStatus.(All, ACTIVE, INACTIVE,ONETIME and RECURRING).

This indicates whether the coupon is to be applied only once, particular number of times or every time an invoice is raised for the subscription. It can either be one_time, duration, forever.

status

string

Status of the coupon. It can either be active, inactive, expired or maxed_out

discount_by

string

Percentage off or Flat rate discounts can be offered. The value can either be flat or percentage.

discount_value

double

Value of the discount associated with a coupon. Depending on the value of discount_by, it can be flat discount or a percentage value. Discount will be deducted from the plans/addons the coupon is associated with.

product_id

string

The Product ID of the product for which the coupon has to be created.

max_redemption

integer

Maximum number of subscriptions the coupon can be used for. The status of the coupon will be changed to maxed_out once this limit is reached.

redemption_count

integer

Number of subscriptions the coupon has been used for at present.

expiry_at

string

Date on which the coupon expires. The coupon cannot be applied to new subscriptions after this date. However, coupons with type=forever already applied to subscriptions can still be redeemed.

apply_to_plans

string

The coupon can be applied to all existing plans, selected plans or none of the existing plans. The values can be all, none or select.

List of plans that the coupon needs to be associated with. If a coupon is to be associated with only two plans - "basic" and "professional", then apply_to_plans is set to be selected. Only the plan codes of the plans that need to be associated with the coupon are required.

plan_code

string

The plan code of the plan to which the coupon is to be applied.

name

string

Name of the coupon to be displayed in the interface and invoices.

apply_to_addons

string

The coupon can be applied to all one-time addons,all recurring addons,all addons, selected addons or none of the existing addons. The values can be all_addons, all_recurring,all_onetime, none or select.

List of addons that the coupon needs to be associated with. If a coupon is to be associated with only two addons - "Email Basic" and "Email Professional", then apply_to_addons is set to be selected. Only the addon codes of the addons that need to be associated with the coupon are required.

This indicates whether the coupon is to be applied only once, particular number of times or every time an invoice is raised for the subscription. It can either be one_time, duration, forever.

duration

Required for duration type coupon.

This indicates the number of times the coupon has to applied to the invoices generated for a particular subscription.

discount_by

Required

Percentage off or Flat rate discounts can be offered. The value can either be flat or percentage.

discount_value

Optional

Value of the discount associated with a coupon. Depending on the value of discount_by, it can be flat discount or a percentage value. Discount will be deducted from the plans/addons the coupon is associated with.

product_id

Required

The Product ID of the product for which the coupon has to be created.

max_redemption

Optional

Maximum number of subscriptions the coupon can be used for. The status of the coupon will be changed to maxed_out once this limit is reached.

expiry_at

Optional

Date on which the coupon expires. The coupon cannot be applied to new subscriptions after this date. However, coupons with type=forever already applied to subscriptions can still be redeemed.

apply_to_plans

Optional

The coupon can be applied to all existing plans, selected plans or none of the existing plans. The values can be all, none or select.

List of plans that the coupon needs to be associated with. If a coupon is to be associated with only two plans - "basic" and "professional", then apply_to_plans is set to be selected. Only the plan codes of the plans that need to be associated with the coupon are required.

plan_code

Required

The plan code of the plan to which the coupon is to be applied.

apply_to_addons

Optional

The coupon can be applied to all one-time addons,all recurring addons,all addons, selected addons or none of the existing addons. The values can be all_addons, all_recurring,all_onetime, none or select.

List of addons that the coupon needs to be associated with. If a coupon is to be associated with only two addons - "Email Basic" and "Email Professional", then apply_to_addons is set to be selected. Only the addon codes of the addons that need to be associated with the coupon are required.

List all coupons

List of all coupons. To list Coupons of a particular product use the parameter product_id. To list plans based on the Status, use the parameter filter_by. The allowed values for filter_by are CouponStatus.(All, ACTIVE, INACTIVE and EXPIRED).

GET /coupons?filter_by=CouponStatus.EXPIRED&product_id=903000000045027

Currency code of the currency in which the customer wants to pay. If currency_code is not specified here, the currency chosen in your Zoho Subscriptions organization will be used for billing.

ach_supported

Optional

Set to true if ACH payment is supported for the customer.

twitter

Optional

Twitter profile of the customer.

facebook

Optional

Facebook profile of the customer.

skype

Optional

Skype ID of the customer

notes

Optional

A short note about the customer.

is_portal_enabled

Optional

Is Client portal enabled for the customer.

gst_no

Applicable for India GST

Optional

GSTIN Number for the customer.

gst_treatment

Applicable for India GST

Optional

GST Treatment for the customer.Allowed values for gst_treatment : business_gst, business_none, consumer, overseasbusiness_gst - For a GST Registered business owner. business_none - For a GST unregistered business owner. consumer - For a consumer. overseas - Customer for whom you export your goods/services.

place_of_contact

Applicable for India GST

Optional

Customer's place of contact.

vat_treatment

Applicable for VAT

Optional

VAT treatment for the customer. VAT treatment denotes the location of the customer, if the customer resides in UK then the VAT treatment is uk. If the customer is in a EU country & if he is VAT registered then his VAT treatment is eu_vat_registered, if he resides in EU & if he is not VAT registered then his VAT treatment is eu_vat_not_registered and if he resides outside the EU then his VAT treatment is non_eu.

vat_reg_no

Applicable for VAT

Optional

VAT Registration number of a contact with VAT treatment as eu_vat_registered. Length should be between 2 and 12 characters. (This node is only available for EU VAT registered customers.)

country_code

Applicable for VAT

Optional

Two letter country code of a contact with VAT treatment as eu_vat_registered. (This node is only available for EU VAT registered customers.)

is_taxable

Applicable for Sales Tax/GST

Optional

Set to true if customer's transactions must be tax inclusive.

tax_id

Optional

Unique ID of the tax or tax group that can be collected from the contact. Tax can be given only if is_taxable is true.

tax_authority_id

Required for applying Tax exemption to a customer.

Unique ID of the tax authority. Tax authority depends on the location of the customer. For example, if the customer is located in NY, then the tax authority is NY tax authority.

tax_authority_name

Applicable for Sales Tax

Required for applying Tax exemption to a customer.

Unique name of the tax authority. Either tax_authority_id or tax_authority_name can be given.

Retrieve a customer Using CRM Reference

Details of an existing customer using CRM Reference ID. reference_id can be CRM Contact ID (for Contacts only sync) or CRM Account ID (For accounts only and Accounts and its contacts sync). Query param value of reference_id_type must be given accoridngly, possible values are zcrm_account_id and zcrm_contact_id.

GET /customers/reference/{reference_id}?reference_id_type=zcrm_account_id

Currency code of the currency in which the customer wants to pay. If currency_code is not specified here, the currency chosen in your Zoho Subscriptions organization will be used for billing.

twitter

Optional

Twitter profile of the customer.

facebook

Optional

Facebook profile of the customer.

skype

Optional

Skype ID of the customer

is_portal_enabled

Optional

Is Client portal enabled for the customer.

gst_no

Applicable for India GST

Optional

GSTIN Number for the customer.

gst_treatment

Applicable for India GST

Optional

GST Treatment for the customer.Allowed values for gst_treatment : business_gst, business_none, consumer, overseasbusiness_gst - For a GST Registered business owner. business_none - For a GST unregistered business owner. consumer - For a consumer. overseas - Customer for whom you export your goods/services.

place_of_contact

Applicable for India GST

Optional

Customer's place of contact.

vat_treatment

Applicable for VAT

Optional

VAT treatment for the customer. VAT treatment denotes the location of the customer, if the customer resides in UK then the VAT treatment is uk. If the customer is in a EU country & if he is VAT registered then his VAT treatment is eu_vat_registered, if he resides in EU & if he is not VAT registered then his VAT treatment is eu_vat_not_registered and if he resides outside the EU then his VAT treatment is non_eu.

vat_reg_no

Applicable for VAT

Optional

VAT Registration number of a contact with VAT treatment as eu_vat_registered. Length should be between 2 and 12 characters. (This node is only available for EU VAT registered customers.)

country_code

Applicable for VAT

Optional

Two letter country code of a contact with VAT treatment as eu_vat_registered. (This node is only available for EU VAT registered customers.)

is_taxable

Applicable for Sales Tax/GST

Optional

Set to true if customer's transactions must be tax inclusive.

tax_id

Optional

Unique ID of the tax or tax group that can be collected from the contact. Tax can be given only if is_taxable is true.

tax_authority_id

Applicable for Sales Tax

Required for applying Tax exemption to a customer.

Unique ID of the tax authority. Tax authority depends on the location of the customer. For example, if the customer is located in NY, then the tax authority is NY tax authority.

tax_authority_name

Applicable for Sales Tax

Required for applying Tax exemption to a customer.

Unique name of the tax authority. Either tax_authority_id or tax_authority_name can be given.

List all customers

List of all customers. You can list customers based on various filter criterias. The allowed values for filter_by are Status.(All, Active, Inactive, Gapps, Crm, NonSubscribers, PortalEnabled, PortalDisabled).

List of transactions

List of all transactions associated with a particular customer.Transactions of particular type can be filtered by passing a param filter_by. The allowed values for filter_by are TransactionType.(All, INVOICE, PAYMENT, CREDIT, REFUND).

GET /transactions?filter_by=TransactionType.All&customer_id=903000000000099

Attribute

Name generated by concatenation of the product name and the selected plan.

status

string

The status of the subscription. It can be live, trial, dunning, unpaid, non_renewing, cancelled, creation_failed, cancelled_from_dunning, expired, trial_expired or future.

amount

double

The amount that needs to be charged for the subscription.

created_at

string

Date at which the subscription was created.

activated_at

string

Date at which the subscription was activated.

current_term_starts_at

string

Date on which the current term of the subscription started.

current_term_ends_at

string

Date on which the current term of the subscription ends.

last_billing_at

string

The date on which the customer was billed last.

next_billing_at

string

The date on which the customer will be billed next. This will also be the date on which the next term of the subscription starts.

expires_at

string

This is applicable only when billing_cycle is set for a plan. A subscription expires on the last day of the last billing cycle.

interval

string

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

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

auto_collect

boolean

auto_collect is set to true for creating an online subscription which will charge the customer’s card automatically on every renewal. To create an offline subscriptions, set auto_collect to false.

created_time

string

Time at which the subscription was created.

updated_time

string

Time at which the subscription details were last updated.

reference_id

string

A string of your choice is required to easily identify and keep track of your subscriptions.

salesperson_id

string

Unique Id of the sales person assigned for the subscription.

salesperson_name

string

Name of the sales person assigned for the subscription.

child_invoice_id

string

Invoice ID of the most recent invoice to which the subscription is associated with.

currency_code

string

Currency code of the currency in which the customer wants to pay. If currency_code is not specified here, the currency chosen in your Zoho Subscriptions organization will be used for billing. currency_id and currency_symbol are set automatically in accordance to the currency_code.

currency_symbol

string

Symbol of the customer's currency.

end_of_term

boolean

If there are any changes in the plan's subscriptions, those subscription changes can be made immediately if end_of_term is set to false. If end_of_term is set to true, the subscription changes take effect only after the current term of the subscription ends.

Plan object for which the subscription is to be created. This contains plan_code, name, price, quantity.

plan_code

string

Plan code of the plan that is to be subscribed to the customer.

name

string

Name generated by concatenation of the product name and the selected plan.

quantity

integer

Required quantity of the chosen plan.

price

double

Price of a plan for a particular subscription. If a value is provided here, the plan’s price for this subscription will be changed to the given value. If no value is provided, the plan’s price would be the same as what it was when it was created.

quantity

integer

Required quantity of the chosen plan.

discount

double

Discount amount applied for the plan.

total

double

Total amount for the plan.

setup_fee

double

Setup fee for the plan.

plan_description

string

Description of the plan exclusive to this subscription. This will be displayed in place of the plan name in invoices generated for this subscription.

tax_id

string

Unique ID of the tax or tax group that can be collected from the contact. Tax can be given only if is_taxable is true.

trial_days

integer

Number of free trial days granted to a customer subscribed to this plan. Trial days for the subscription mentioned here will override the number of trial days provided at the time plan creation. This will be applicable even if exclude_trial=true.

List of addon objects which are to be included in the subscription. Each object contains addon_code, name, price and quantity.

addon_code

string

Addon code of the addon.

name

string

Name generated by concatenation of the product name and the selected plan.

addon_description

string

Description of the addon exclusive to this subscription. This will be displayed in place of the addon name in invoices generated for this subscription.

quantity

integer

Required quantity of the chosen plan.

price

double

Price of a plan for a particular subscription. If a value is provided here, the plan’s price for this subscription will be changed to the given value. If no value is provided, the plan’s price would be the same as what it was when it was created.

discount

double

Discount amount applied for the plan.

total

double

Total amount for the plan.

tax_id

string

Unique ID of the tax or tax group that can be collected from the contact. Tax can be given only if is_taxable is true.

GST Treatment for the customer.Allowed values for gst_treatment : business_gst, business_none, consumer, overseasbusiness_gst - For a GST Registered business owner. business_none - For a GST unregistered business owner. consumer - For a consumer. overseas - Customer for whom you export your goods/services.

vat_treatment

Applicable for VAT

Optional

VAT treatment for the credit-note. VAT treatment denotes the location of the customer, if the customer resides in UK then the VAT treatment is uk. If the customer is in a EU country & if he is VAT registered then his VAT treatment is eu_vat_registered, if he resides in EU & if he is not VAT registered then his VAT treatment is eu_vat_not_registered and if he resides outside the EU then his VAT treatment is non_eu.

vat_reg_no

Applicable for VAT

Optional

VAT Registration number of a contact with VAT treatment as eu_vat_registered. Length should be between 2 and 12 characters. (This node is only available for EU VAT registered customers.)

country_code

Applicable for VAT

Optional

Two letter country code of a contact with VAT treatment as eu_vat_registered. (This node is only available for EU VAT registered customers.)

is_taxable

Applicable for Sales Tax/GST

Optional

Set to true if customer's transactions must be tax inclusive.

tax_id

Required

Unique ID of the tax or tax group that can be collected from the contact. Tax can be given only if is_taxable is true.

tax_authority_id

Applicable for Sales Tax

Required for applying Tax exemption to a customer.

Unique ID of the tax authority. Tax authority depends on the location of the customer. For example, if the customer is located in NY, then the tax authority is NY tax authority.

tax_authority_name

Applicable for Sales Tax

Required for applying Tax exemption to a customer.

Unique name of the tax authority. Either tax_authority_id or tax_authority_name can be given.

tax_exemption_id

Applicable for Sales Tax/GST

Optional

Unique ID of the tax exemption.

tax_exemption_code

Applicable for Sales Tax/GST

Optional

Unique code of the tax exemption.

customer_id

Required for creating a subscription for existing customer.

Customer ID of the customer for whom a subscription needs to be created.

Generally the subscription will start on the day it is created. But, the date can also be a future or past date depending upon your usecase. For future dates, the subscription status would be Future till the starts_at date. And for past dates, the subscription status can be Trial, Live or Expired depending on the subscription interval that you have selected.

exchange_rate

Optional , default is the exchange rate provided in settings.

This will be the exchange rate provided for the organization's currency and the customer's currency. The subscription fee would be the multiplicative product of the original price and the exchange rate.

Plan object for which the subscription is to be created. This contains plan_code, name, price, quantity.

plan_code

Required

Plan code of the plan that is to be subscribed to the customer.

plan_description

Optional

Description of the plan exclusive to this subscription. This will be displayed in place of the plan name in invoices generated for this subscription.

price

Optional

Price of a plan for a particular subscription. If a value is provided here, the plan’s price for this subscription will be changed to the given value. If no value is provided, the plan’s price would be the same as what it was when it was created.

setup_fee

Optional , default is 0 only if exclude_setup_fee is true

Setup fee for the plan.

setup_fee_tax_id

Optional

Unique ID for tax of setup fee. setup_fee_tax_id must be empty for applying tax Exemption.

Unique ID of the tax or tax group that can be collected from the contact. Tax can be given only if is_taxable is true.

tax_exemption_id

Applicable for Sales Tax/GST

Optional

Unique ID of the tax exemption.

tax_exemption_code

Applicable for Sales Tax/GST

Optional

Unique code of the tax exemption.

setup_fee_tax_exemption_id

Applicable for Sales Tax/GST

Optional

Unique Tax Exemption ID that must be applied to setup fee.

setup_fee_tax_exemption_code

Applicable for Sales Tax/GST

Optional

Unique code of the tax exemption that must be applied to setup fee.

exclude_trial

Optional

This is set to true if the respective plan's trial period needs to be excluded for this subscription.

exclude_setup_fee

Optional

This is set to true if the respective plan's setup fee needs to be excluded for this subscription.

billing_cycles

Optional

billing_cycles specified at the time of creation of the plan would be the default value. If this needs to be overridden for this particular subscription, a value can be provided here.

trial_days

Optional , default is 0 only if exclude_trial is true

Number of free trial days granted to a customer subscribed to this plan. Trial days for the subscription mentioned here will override the number of trial days provided at the time plan creation. This will be applicable even if exclude_trial=true.

List of addon objects which are to be included in the subscription. Each object contains addon_code, name, price and quantity.

addon_code

Required

Addon code of the addon.

addon_description

Optional

Description of the addon exclusive to this subscription. This will be displayed in place of the addon name in invoices generated for this subscription.

price

Optional

Price of a plan for a particular subscription. If a value is provided here, the plan’s price for this subscription will be changed to the given value. If no value is provided, the plan’s price would be the same as what it was when it was created.

ARGUMENTS

card_id

Required if auto_collect is true.

Enter the card_id of the card which has to be updated.

exchange_rate

Optional , default is the exchange rate provided in settings.

This will be the exchange rate provided for the organization's currency and the customer's currency. The subscription fee would be the multiplicative product of the original price and the exchange rate.

Plan object for which the subscription is to be created. This contains plan_code, name, price, quantity.

plan_code

Required

Plan code of the plan that is to be subscribed to the customer.

plan_description

Optional

Description of the plan exclusive to this subscription. This will be displayed in place of the plan name in invoices generated for this subscription.

price

Optional

Price of a plan for a particular subscription. If a value is provided here, the plan’s price for this subscription will be changed to the given value. If no value is provided, the plan’s price would be the same as what it was when it was created.

Unique ID of the tax or tax group that can be collected from the contact. Tax can be given only if is_taxable is true.

tax_exemption_id

Applicable for Sales Tax/GST

Optional

Unique ID of the tax exemption.

tax_exemption_code

Applicable for Sales Tax/GST

Optional

Unique code of the tax exemption.

setup_fee_tax_exemption_id

Applicable for Sales Tax/GST

Optional

Unique Tax Exemption ID that must be applied to setup fee.

setup_fee_tax_exemption_code

Applicable for Sales Tax/GST

Optional

Unique code of the tax exemption that must be applied to setup fee.

exclude_trial

Optional

This is set to true if the respective plan's trial period needs to be excluded for this subscription.

exclude_setup_fee

Optional

This is set to true if the respective plan's setup fee needs to be excluded for this subscription.

billing_cycles

Optional

billing_cycles specified at the time of creation of the plan would be the default value. If this needs to be overridden for this particular subscription, a value can be provided here.

trial_days

Optional , default is 0 only if exclude_trial is true

Number of free trial days granted to a customer subscribed to this plan. Trial days for the subscription mentioned here will override the number of trial days provided at the time plan creation. This will be applicable even if exclude_trial=true.

List of addon objects which are to be included in the subscription. Each object contains addon_code, name, price and quantity.

addon_code

Required

Addon code of the addon.

addon_description

Optional

Description of the addon exclusive to this subscription. This will be displayed in place of the addon name in invoices generated for this subscription.

price

Optional

Price of a plan for a particular subscription. If a value is provided here, the plan’s price for this subscription will be changed to the given value. If no value is provided, the plan’s price would be the same as what it was when it was created.

Unique ID of the tax or tax group that can be collected from the contact. Tax can be given only if is_taxable is true.

tax_exemption_id

Applicable for Sales Tax/GST

Optional

Unique ID of the tax exemption.

tax_exemption_code

Applicable for Sales Tax/GST

Optional

Unique code of the tax exemption.

auto_collect

Optional

auto_collect is set to true for creating an online subscription which will charge the customer’s card automatically on every renewal. To create an offline subscriptions, set auto_collect to false.

coupon_code

Optional

The coupon code of the coupon which is to be applied to the subscription.

reference_id

Optional

A string of your choice is required to easily identify and keep track of your subscriptions.

salesperson_id

Optional

Unique Id of the sales person assigned for the subscription.

salesperson_name

Optional

Name of the sales person assigned for the subscription.

end_of_term

Optional

If there are any changes in the plan's subscriptions, those subscription changes can be made immediately if end_of_term is set to false. If end_of_term is set to true, the subscription changes take effect only after the current term of the subscription ends.

Defaulte Invoice Template ID for all the invoices created from the subscription.

Cancel a subscription

Your subscription can be either cancelled immediately or at the end of the current term based on the value of `cancel_at_end`. If `cancel_at_end` is set to true then the `status` of the subscription is changed to non_renewing and if it is false, the `status` would be cancelled.

Price of a plan for a particular subscription. If a value is provided here, the plan’s price for this subscription will be changed to the given value. If no value is provided, the plan’s price would be the same as what it was when it was created.

tax_id

Required

Unique ID of the tax or tax group that can be collected from the contact. Tax can be given only if is_taxable is true.

tax_exemption_id

Applicable for Sales Tax/GST

Optional

Unique ID of the tax exemption.

tax_exemption_code

Applicable for Sales Tax/GST

Optional

Unique code of the tax exemption.

product_type

Applicable for VAT

Optional

Product type for UK Edition.

exchange_rate

Optional , default is the exchange rate provided in settings.

This will be the exchange rate provided for the organization's currency and the customer's currency. The subscription fee would be the multiplicative product of the original price and the exchange rate.

coupon_code

Optional

The coupon code of the coupon which is to be applied to the one-time addon.

exchange_rate

Optional , default is the exchange rate provided in settings.

This will be the exchange rate provided for the organization's currency and the customer's currency. The subscription fee would be the multiplicative product of the original price and the exchange rate.

Attribute

Unique invoice number (starts with INV) generated for an invoice which will be used to display in interface and invoices.

status

string

Status of the invoice. It can be paid, sent, overdue, partially_paid or void.

invoice_date

string

The date on which the invoice is raised.

due_date

string

Date on which the invoice is due. If the invoice is not fully paid on or before this date, the status of the invoice will be changed to overdue. If the invoice is only partially paid, its status will be partially_paid.

The list of items which are all included in the invoice. Each item object will have item_id, name, code, price, quantity and item_total.
description: Small description about the Invoice item.
example: "Charges for this duration (from 16-April-2016 to 8-June-2016)"

ARGUMENTS

The list of items which are all included in the invoice. Each item object will have item_id, name, code, price, quantity and item_total.
description: Small description about the Invoice item.
example: "Charges for this duration (from 16-April-2016 to 8-June-2016)"

code

Optional

Item code of the item included in the invoice.

product_id

Optional

The ID of the product included in the invoice.

name

Optional

Name of the item included in the invoice.

description

Optional

Small description of the payment made for the invoice.

price

Optional

Price of the item included in the invoice.

quantity

Optional

Quantity of the item included in the invoice.

tax_id

Optional

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

tax_exemption_id

Optional

Unique Tax Exemption ID if you dont want to associate a tax to the plan.

If the payment mode is autotransaction, autotransaction information will be displayed in the autotransaction object. It contains autotransaction_id, payment_gateway, gateway_transaction_id, card_id, last_four_digits, expiry_month and expiry_year.

If the refund mode is autotransaction, autotransaction information will be displayed in the autotransaction object. It contains autotransaction_id, payment_gateway, gateway_transaction_id, card_id, last_four_digits, expiry_month and expiry_year.

autotransaction_id

string

Auto-transaction ID generated for the payment made.

payment_gateway

string

Name of the payment gateway associated with payment.

gateway_transaction_id

string

Transaction ID of the gateway associated with payment.

gateway_error_message

string

Gateway error for a failed transaction.

card_id

string

Card ID of the card.

last_four_digits

integer

Last four digits of the card.

expiry_month

integer

Expiry month of the card.

expiry_year

integer

Expiry year of the card.

currency_code

string

Customer's currency code. Refunds will be made in the customer's currency.

Hosted-Pages

Zoho Subscriptions provides a hosted payment page to integrate with your websites. You can securely integrate with Zoho Subscriptions for collecting your customer's sensitive card information through the hosted page. These Hosted Pages will expire within one hour.

Attribute

Unique ID generated by the server. This is used to identify the generated hosted page.

status

string

Status of the hosted page generated. This can be fresh, read, success, failed, cancelled or force_cancelled.

url

string

The URL of the hosted page generated.

action

string

Action that needs to be performed using the hosted page. This can be new_subscription, update_subscription, update_card or one_time_addon.

expiring_time

string

The time at which the hosted page will expire.

created_time

string

The time at which the hosted page was created.

Retrieve a hosted page

Details of a specific hosted page. The data field will be populated with the subscription details in case of successfull subscription via Hostedpage. In case of fresh hosted pages the data field will be empty.

Create a subscription

Create a hosted page for a new subscription. To create a subscription for a new customer, you have to pass the customer object. To create a subscription for a existing customer pass the customer_id of that customer.

This will be the exchange rate provided for the organization's currency and the customer's currency. The subscription fee would be the multiplicative product of the original price and the exchange rate.

currency_code

Optional

Currency code of the currency in which the customer wants to pay. If currency_code is not specified here, the currency chosen in your Zoho Subscriptions organization will be used for billing. currency_id and currency_symbol are set automatically in accordance to the currency_code.

vat_treatment

Applicable for VAT

Optional

VAT treatment for the credit-note. VAT treatment denotes the location of the customer, if the customer resides in UK then the VAT treatment is `uk`. If the customer is in a EU country & if he is VAT registered then his VAT treatment is `eu_vat_registered`, if he resides in EU & if he is not VAT registered then his VAT treatment is `eu_vat_not_registered` and if he resides outside the EU then his VAT treatment is `non_eu`.

vat_reg_no

Applicable for VAT

Optional

VAT Registration number of a contact with VAT treatment as eu_vat_registered. Length should be between 2 and 12 characters. (This node is only available for EU VAT registered customers.)

country_code

Applicable for VAT

Optional

Two letter country code of a contact with VAT treatment as eu_vat_registered. (This node is only available for EU VAT registered customers.)

is_taxable

Applicable for Sales Tax/GST

Optional

Set to true if customer's transactions must be tax inclusive.

tax_id

Required

Unique ID of the tax or tax group that can be collected from the contact. Tax can be given only if is_taxable is true.

tax_authority_id

Applicable for Sales Tax

Required

Unique ID of the tax authority. Tax authority depends on the location of the customer. For example, if the customer is located in NY, then the tax authority is NY tax authority.

Plan object for which the subscription is to be created/updated. This contains plan_code, name, price, exclude_setup_fee, quantity, exclude_setup_fee, exclude_trial, billing_cycles and trial_days.

plan_code

Required

Plan code of the plan that is to be subscribed to the customer.

plan_description

Optional

Description of the plan exclusive to this subscription. This will be displayed in place of the plan name in invoices generated for this subscription.

price

Optional

Price of a plan for a particular subscription. If a value is provided here, the plan’s price for this subscription will be changed to the given value. If no value is provided, the plan’s price would be the same as what it was when it was created.

setup_fee

Optional , default is 0 only if exclude_setup_fee is true

Setup fee for the plan.

setup_fee_tax_id

Optional

Unique ID for tax of setup fee. setup_fee_tax_id must be empty for applying tax Exemption.

Unique ID of the tax or tax group that can be collected from the contact. Tax can be given only if is_taxable is true.

tax_exemption_id

Applicable for Sales Tax/GST

Optional

Unique ID of the tax exemption.

tax_exemption_code

Applicable for Sales Tax/GST

Optional

Unique code of the tax exemption.

setup_fee_tax_exemption_id

Applicable for Sales Tax/GST

Optional

Unique Tax Exemption ID that must be applied to setup fee.

setup_fee_tax_exemption_code

Applicable for Sales Tax/GST

Optional

Unique code of the tax exemption that must be applied to setup fee.

exclude_trial

Optional

This is set to true if the respective plan's trial period needs to be excluded for this subscription.

exclude_setup_fee

Optional

This is set to true if the respective plan's setup fee needs to be excluded for this subscription.

billing_cycles

Optional

billing_cycles specified at the time of creation of the plan would be the default value. If this needs to be overridden for this particular subscription, a value can be provided here.

trial_days

Optional , default is 0 only if exclude_trial is true

Number of free trial days granted to a customer subscribed to this plan. Trial days for the subscription mentioned here will override the number of trial days provided at the time plan creation. This will be applicable even if exclude_trial=true.

List of addon objects which are to be included in the subscription. Each object contains addon_code, name, price and quantity.

addon_code

Required

Addon code of the addon.

addon_description

Optional

Description of the addon exclusive to this subscription. This will be displayed in place of the addon name in invoices generated for this subscription.

price

Optional

Price of a plan for a particular subscription. If a value is provided here, the plan’s price for this subscription will be changed to the given value. If no value is provided, the plan’s price would be the same as what it was when it was created.

Unique ID of the tax or tax group that can be collected from the contact. Tax can be given only if is_taxable is true.

tax_exemption_id

Applicable for Sales Tax/GST

Optional

Unique ID of the tax exemption.

tax_exemption_code

Applicable for Sales Tax/GST

Optional

Unique code of the tax exemption.

reference_id

Optional

A string of your choice is required to easily identify and keep track of your subscriptions.

starts_at

Optional

Generally the subscription will start on the day it is created. But, the date can also be a future or past date depending upon your usecase. For future dates, the subscription status would be Future till the starts_at date. And for past dates, the subscription status can be Trial, Live or Expired depending on the subscription interval that you have selected.

ARGUMENTS

Plan object for which the subscription is to be created/updated. This contains plan_code, name, price, exclude_setup_fee, quantity, exclude_setup_fee, exclude_trial, billing_cycles and trial_days.

plan_code

Required

Plan code of the plan that is to be subscribed to the customer.

plan_description

Optional

Description of the plan exclusive to this subscription. This will be displayed in place of the plan name in invoices generated for this subscription.

price

Optional

Price of a plan for a particular subscription. If a value is provided here, the plan’s price for this subscription will be changed to the given value. If no value is provided, the plan’s price would be the same as what it was when it was created.

Unique ID of the tax or tax group that can be collected from the contact. Tax can be given only if is_taxable is true.

tax_exemption_id

Applicable for Sales Tax/GST

Optional

Unique ID of the tax exemption.

tax_exemption_code

Applicable for Sales Tax/GST

Optional

Unique code of the tax exemption.

setup_fee_tax_exemption_id

Applicable for Sales Tax/GST

Optional

Unique Tax Exemption ID that must be applied to setup fee.

setup_fee_tax_exemption_code

Applicable for Sales Tax/GST

Optional

Unique code of the tax exemption that must be applied to setup fee.

exclude_trial

Optional

This is set to true if the respective plan's trial period needs to be excluded for this subscription.

exclude_setup_fee

Optional

This is set to true if the respective plan's setup fee needs to be excluded for this subscription.

billing_cycles

Optional

billing_cycles specified at the time of creation of the plan would be the default value. If this needs to be overridden for this particular subscription, a value can be provided here.

trial_days

Optional , default is 0 only if exclude_trial is true

Number of free trial days granted to a customer subscribed to this plan. Trial days for the subscription mentioned here will override the number of trial days provided at the time plan creation. This will be applicable even if exclude_trial=true.

List of addon objects which are to be included in the subscription. Each object contains addon_code, name, price and quantity.

addon_code

Required

Addon code of the addon.

addon_description

Optional

Description of the addon exclusive to this subscription. This will be displayed in place of the addon name in invoices generated for this subscription.

price

Optional

Price of a plan for a particular subscription. If a value is provided here, the plan’s price for this subscription will be changed to the given value. If no value is provided, the plan’s price would be the same as what it was when it was created.

Unique ID of the tax or tax group that can be collected from the contact. Tax can be given only if is_taxable is true.

tax_exemption_id

Applicable for Sales Tax/GST

Optional

Unique ID of the tax exemption.

tax_exemption_code

Applicable for Sales Tax/GST

Optional

Unique code of the tax exemption.

auto_collect

Optional

auto_collect is set to true for charging customer's card automatically.

reference_id

Optional

A string of your choice is required to easily identify and keep track of your subscriptions.

starts_at

Optional

Generally the subscription will start on the day it is created. But, the date can also be a future or past date depending upon your usecase. For future dates, the subscription status would be Future till the starts_at date. And for past dates, the subscription status can be Trial, Live or Expired depending on the subscription interval that you have selected.

Price of a plan for a particular subscription. If a value is provided here, the plan’s price for this subscription will be changed to the given value. If no value is provided, the plan’s price would be the same as what it was when it was created.

tax_id

Required

Unique ID of the tax or tax group that can be collected from the contact. Tax can be given only if is_taxable is true.

tax_exemption_id

Applicable for Sales Tax/GST

Optional

Unique ID of the tax exemption.

tax_exemption_code

Applicable for Sales Tax/GST

Optional

Unique code of the tax exemption.

product_type

Applicable for VAT

Optional

Product type for UK Edition.

redirect_url

Optional

It specifies the url to which the customer will be redirected after successful transaction.

coupon_code

Optional

The coupon code of the coupon which is to be applied to the one-time addon.

Events

Events can be used to let you know when something happens in your organization. Every happening in your organization will be recorded as a new Event. For example, when a new payment is received, we will create a payment_thankyou event; when a subscription is created, we will create a subscription_created event.

You can retrieve these events individually or as a list using our API. If you want to update the data on your server when an event occurs, you can use webhooks to send these event objects directly to an endpoint on your application’s server. Learn more about webhooks.