API Documentation
Introduction

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.

Getting Started

Example

$ curl https://subscriptions.zoho.com/api/v1/organizations -H 'Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5' -H 'X-com-zoho-subscriptions-organizationid: 10234695'

All Zoho Subscriptions APIs requires a minimum of two mandatory headers.

  1. Authorization - Authentication request header.
  2. X-com-zoho-subscriptions-organizationid - the header that contains the organization ID of the organization you need to access.

Authentication

All Zoho Subscriptions API need to be authenticated using an authtoken.

You can obtain an authtoken by the following ways:

  1. Through a URL in your browser.
  2. Programmatically using the Zoho Accounts API.

Sample Success Response

# #Fri Apr 11 06:14:13 PST 2016 AUTHTOKEN=ba4604e8e433g9c892e360d53463oec5 RESULT=TRUE

Sample Error Response

# #Fri Apr 11 06:32:13 PST 2016 CAUSE=INVALID_API_AUTHTOKEN_SCOPE RESULT=FALSE

In your browser

Obtaining an authtoken in your browser is very simple. Login to your Zoho Account and go to the URL below.

https://accounts.zoho.com/apiauthtoken/create?SCOPE=ZohoSubscriptions/subscriptionsapi

Programmatically using the API

If you chosen to obtain your authtoken via an API, please follow the instructions below:

Submit an HTTP POST request to the below URL.

https://accounts.zoho.com/apiauthtoken/nb/create.

The POST body should include a string in the below format.

?SCOPE=ZohoSubscriptions/subscriptionsapi&EMAIL_ID=[ZohoID/EmailID]&PASSWORD=[Password]

Below are the mandatory case sensitive fields to be passed in the URL.

Parameter Description
SCOPE ZohoSubscriptions/subscriptionsapi
EMAIL_ID Your Zoho ID or Email ID.
PASSWORD Your Zoho password or your TFA*

* To know more about TFA and creating application password click here.

Points To Note

Organization ID

Request Example

$ curl https://subscriptions.zoho.com/api/v1/organizations \ -H 'Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5'

Response Example

HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "organizations": [ { "organization_id": "10234695", "name": "Zillum", "contact_name": "John Smith", "email": "johnsmith@zillum.com", "is_default_org": false, "language_code": "en", "fiscal_year_start_month": 0, "account_created_date": "2016-02-18", "time_zone": "PST", "is_org_active": true, "currency_id": "460000000000097", "currency_code": "USD", "currency_symbol": "$", "currency_format": "###,##0.00", "price_precision": 2 }, {...}, {...} ]

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.

Manage Organizations

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

Organization ID

HTTP Methods

Using GET method, you can get the list of resources or details of a particular instance of a resource. To get a list of customers
$ curl https://subscriptions.zoho.com/api/v1/customers \ -H 'Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5' \ -H 'X-com-zoho-subscriptions-organizationid: 10234695'
To get the details of a customer referred to by a specified customer_id
$ curl https://subscriptions.zoho.com/api/v1/customers/903000000000099 \ -H 'Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5' \ -H 'X-com-zoho-subscriptions-organizationid: 10234695'

Zoho Subscriptions API uses appropriate HTTP verbs for every action.

Method Description
GET Used for retrieving resources.
POST Used for creating resources and performing resource actions.
PUT Used for updating resources.
DELETE Used for deleting resources.

Response

Response Structure

The response structure for the invoice API follows the below format.
{ "code" : 0, "message" : "success", "invoice" : { "invoice_id" : "..." } }

Request Example

$ curl https://subscriptions.zoho.com/api/v1/invoices/7000000079426 \ -H 'Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5' \ -H 'X-com-zoho-subscriptions-organizationid: 10234695' \ -H 'Accept: application/pdf'
OR
$ curl https://subscriptions.zoho.com/api/v1/invoices/7000000079426?accept=pdf \ -H 'Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5' \ -H 'X-com-zoho-subscriptions-organizationid: 10234695'

Responses will be in the JSON format.

Node Name Description
code Zoho Subscriptions error code. This will be zero for a success response and non-zero in case of an error.
message Message for the invoked API.
resource name Comprises the invoked API’s Data.

Response Header Example

HTTP/1.1 200 OK Content-Disposition: attachment; filename="INV-384.pdf" Content-Type: application/pdf;charset=UTF-8


Other Formats

Certain APIs support csv and pdf formats as well for which the required response format need to be specified in the respective request’s Accept header or accept query parameter.



















Date

All timestamps are returned in the ISO 8601 format - YYYY-MM-DDThh:mm:ssTZD.

Example: 2016-06-11T17:38:06-0700

Errors

Request Example

$ curl https://subscriptions.zoho.com/api/v1/invoices/700000007942 \ -H 'Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5' \ -H 'X-com-zoho-subscriptions-organizationid: 10234695'

Response Example

HTTP/1.1 201 Successfully Created Content-Type: application/json;charset=UTF-8 { "code": 0, "message": "Successfully created." }
HTTP/1.1 404 Not Found Content-Type: application/json;charset=UTF-8 { "code": 1002, "message": "Invoice does not exist." }
HTTP/1.1 500 Internal error Content-Type: application/json;charset=UTF-8 { "code": 1000, "message": "Internal error" }

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
2xxSuccess
4xxBad request sent to server
5xxServer 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 Found The 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 requests Too 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.

Pagination

Example

$ curl https://subscriptions.zoho.com/api/v1/customers?page=2&per_page=25 -H 'Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5' \ -H 'X-com-zoho-subscriptions-organizationid: 10234695' { "code": 0, "message": "success", "customers": [ {...}, {...} ], "page_context": { "page": 2, "per_page": 25, "has_more_page": false } }

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.

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:

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.

  1. Download the sample environment file.
  2. Replace the values for domain-url, organization_id, authtoken .

    domain-url: subscriptions.zoho.com

    organization_id: organization ID

    authtoken: authtoken

  3. In the Postman app, click the settings icon (cog icon) on the top-right and go to
    Manage Environment
  4. 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.

Example

{ "product_id": "903000000045027", "name": "PiperHost", "description": "Dedicated server for web hosting", "email_ids": "piper@zillum.com", "redirect_url": "http://www.zillum.com/products/piperhost", "status": "active", "created_time": "2016-06-05T17:38:06-0700", "updated_time": "2016-06-05T20:09:23-0700" }

Attribute

product_id
string
Unique ID generated by the server for the product.
name
string
Name of your choice to be displayed in the interface.
description
string
Short description regarding the product.
email_ids
string
The email IDs to which notifications related to the product need to be sent. (Use comma separation for multiple email-ids)
redirect_url
string
The URL to which customers should be redirected to once they subscribe to the product.
status
string
Status of the product. It can be active or inactive
created_time
string
The time at which the product was created.
updated_time
string
The time at which the product details were last updated.

Create a product

Create a new product.

POST /products

Request Example

  
$ curl https://subscriptions.zoho.com/api/v1/products -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "X-com-zoho-subscriptions-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8" -d '{ "name": "PiperHost", "description": "Dedicated server for web hosting", "email_ids": "piper@zillum.com", "redirect_url": "http://www.zillum.com/products/piperhost" }

Response Example

  
HTTP/1.1 201 Created Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The product has been created", "product": { "product_id": "903000000045027", "name": "PiperHost", "description": "Dedicated server for web hosting", "email_ids": "piper@zillum.com", "redirect_url": "http://www.zillum.com/products/piperhost", "status": "active", "created_time": "2016-06-05T17:38:06-0700", "updated_time": "2016-06-05T20:09:23-0700" } }

ARGUMENTS

name
Required
Name of your choice to be displayed in the interface.
description
Optional
Short description regarding the product.
email_ids
Optional
The email IDs to which notifications related to the product need to be sent. (Use comma separation for multiple email-ids)
redirect_url
Optional
The URL to which customers should be redirected to once they subscribe to the product.

Retrieve a product

Details of an existing product.

GET /products/{product_id}

Request Example

  
$ curl https://subscriptions.zoho.com/api/v1/products/{product_id} -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "X-com-zoho-subscriptions-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "product": { "product_id": "903000000045027", "name": "PiperHost", "description": "Dedicated server for web hosting", "email_ids": "piper@zillum.com", "redirect_url": "http://www.zillum.com/products/piperhost", "status": "active", "created_time": "2016-06-05T17:38:06-0700", "updated_time": "2016-06-05T20:09:23-0700" } }

Update a product

Update details of an existing product.

PUT /products/{product_id}

Request Example

  
$ curl https://subscriptions.zoho.com/api/v1/products/{product_id} -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "X-com-zoho-subscriptions-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8" -d '{ "name": "PiperHost", "description": "Dedicated server for web hosting", "email_ids": "piper@zillum.com", "redirect_url": "http://www.zillum.com/products/piperhost" }

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The product details have been updated.", "product": { "product_id": "903000000045027", "name": "PiperHost", "description": "Dedicated server for web hosting", "email_ids": "piper@zillum.com", "redirect_url": "http://www.zillum.com/products/piperhost", "status": "active", "created_time": "2016-06-05T17:38:06-0700", "updated_time": "2016-06-05T20:09:23-0700" } }

ARGUMENTS

name
Required
Name of your choice to be displayed in the interface.
description
Optional
Short description regarding the product.
email_ids
Optional
The email IDs to which notifications related to the product need to be sent. (Use comma separation for multiple email-ids)
redirect_url
Optional
The URL to which customers should be redirected to once they subscribe to the product.

Delete a product

Delete an existing product.

DELETE /products/{product_id}

Request Example

  
$ curl https://subscriptions.zoho.com/api/v1/products/{product_id} -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "X-com-zoho-subscriptions-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The product has been deleted." }

List of all products

List of all created products.

GET /products

Request Example

  
$ curl https://subscriptions.zoho.com/api/v1/products -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "X-com-zoho-subscriptions-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "product": [ { "product_id": "903000000045027", "name": "PiperHost", "description": "Dedicated server for web hosting", "email_ids": "piper@zillum.com", "redirect_url": "http://www.zillum.com/products/piperhost", "status": "active", "created_time": "2016-06-05T17:38:06-0700", "updated_time": "2016-06-05T20:09:23-0700" }, {...}, {...} ] }

Mark as active

The product has been marked as active.

POST /products/{product_id}/markasactive

Request Example

  
$ curl https://subscriptions.zoho.com/api/v1/products/{product_id}/markasactive -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "X-com-zoho-subscriptions-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The product has been marked as active." }

Mark as inactive

The product has been marked as inactive.

POST /products/{product_id}/markasinactive

Request Example

  
$ curl https://subscriptions.zoho.com/api/v1/products/{product_id}/markasinactive -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "X-com-zoho-subscriptions-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The product has been marked as inactive." }

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.

Example

{ "plan_code": "basic-monthly", "name": "Basic", "description": "Basic monthly plan.", "status": "active", "product_id": "903000000045027", "account_id": "903000987009900", "account_name": "903000000045027", "trial_period": 0, "setup_fee": 0, "recurring_price": 400, "interval": 1, "interval_unit": "months", "billing_cycles": -1, "addons": [ { "addon_code": "Email-basic", "name": "Basic" } ], "url": "https://subscriptions.zoho.com/subscribe/3b884751f87f05e584c3952b6388e7f96a2bba0f6b0532177e00f0ba8db832fc/basic-monthly", "tax_id": "903000000065300", "created_time": "2016-06-05T17:40:49-0700", "updated_time": "2016-06-05T24:40:49-0700" }

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.
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.
trial_period
integer
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.
list
List of addons that the plan is associated with. It holds the list of objects with addon_code and name as properties.
addon_code
string
The addon code of the addon which is associated with the plan .
name
string
Name of your choice to be displayed in the interface and invoices.
url
string
Unique url of the plan.
tax_id
string
Tax ID to which you would like to associate with this 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.

Create a plan

Create a new plan.

POST /plans

Request Example

  
$ curl https://subscriptions.zoho.com/api/v1/plans -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "X-com-zoho-subscriptions-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8" -d '{ "plan_code": "basic-monthly", "name": "Basic", "recurring_price": 400, "interval": 1, "interval_unit": "months", "billing_cycles": -1, "trial_period": 0, "setup_fee": 0, "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." }

Response Example

  
HTTP/1.1 201 Created Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The plan has been created.", "plan": { "plan_code": "basic-monthly", "name": "Basic", "description": "Basic monthly plan.", "status": "active", "product_id": "903000000045027", "account_id": "903000987009900", "account_name": "903000000045027", "tax_id": "903000000065300", "trial_period": 0, "setup_fee": 0, "recurring_price": 400, "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": "Basic", "status": "active", "type": "recurring", "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" } }

ARGUMENTS

plan_code
Required
Unique string of your choice which lets you identify this plan.
name
Required
Name of your choice to be displayed in the interface and invoices.
recurring_price
Required
The customer is charged an amount over an interval for the subscription.
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.
product_id
Required
Product ID to which you want to associate this plan with.
product_type
Applicable for VAT/ India GST
Optional
Product type for India/UK Edition.
hsn_or_sac
Applicable for India GST
Optional
HSN or SAC code for Goods/Services plan
item_tax_preferences
Applicable for India GST
Optional
Tax preferenece for plan
tax_specification
Optional
Tax specification for the plan. It can be either inter or intra.
tax_name
Optional
Name of the tax to which subscription is associated.
tax_percentage
Optional
Percentage of tax applied to the plan/addon
tax_id
Optional , default is no tax will be associated
Tax ID to which you would like to associate with this plan.
tax_id
Optional , default is no tax will be associated
Tax ID to which you would like to associate with this plan.
is_taxable
Applicable for Sales Tax/GST
Optional
Set to true if plan must be tax inclusive.
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.
description
Optional
Short description regarding the plan.

Retrieve a plan

Retrieve details of an existing plan.

GET /plans/{plan_code}

Request Example

  
$ curl https://subscriptions.zoho.com/api/v1/plans/{plan_code} -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "X-com-zoho-subscriptions-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "plan": { "plan_code": "basic-monthly", "name": "Basic", "description": "Basic monthly plan.", "status": "active", "product_id": "903000000045027", "account_id": "903000987009900", "account_name": "903000000045027", "trial_period": 0, "setup_fee": 0, "recurring_price": 400, "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" } }

Update a plan

Update details of an existing plan.

PUT /plans/{plan_code}

Request Example

  
$ curl https://subscriptions.zoho.com/api/v1/plans/{plan_code} -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "X-com-zoho-subscriptions-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8" -d '{ "plan_code": "basic-monthly", "name": "Basic", "recurring_price": 400, "interval": 1, "interval_unit": "months", "billing_cycles": -1, "trial_period": 0, "setup_fee": 0, "addons": [ { "addon_code": "Email-basic", "name": "Basic" } ], "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." }

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The plan details has been updated.", "plan": { "plan_code": "basic-monthly", "name": "Basic", "description": "Basic monthly plan.", "status": "active", "product_id": "903000000045027", "account_id": "903000987009900", "account_name": "903000000045027", "trial_period": 0, "setup_fee": 0, "recurring_price": 400, "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" } }

ARGUMENTS

plan_code
Required
Unique string of your choice which lets you identify this plan.
name
Required
Name of your choice to be displayed in the interface and invoices.
recurring_price
Required
The customer is charged an amount over an interval for the subscription.
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.
Optional
List of addons that the plan is associated with. It holds the list of objects with addon_code and name as properties.
addon_code
Optional
The addon code of the addon which is associated with the plan .
name
Required
Name of your choice to be displayed in the interface and invoices.
product_id
Required
Product ID to which you want to associate this plan with.
product_type
Applicable for VAT/ India GST
Optional
Product type for India/UK Edition.
hsn_or_sac
Applicable for India GST
Optional
HSN or SAC code for Goods/Services plan
item_tax_preferences
Applicable for India GST
Optional
Tax preferenece for plan
tax_specification
Optional
Tax specification for the plan. It can be either inter or intra.
tax_name
Optional
Name of the tax to which subscription is associated.
tax_percentage
Optional
Percentage of tax applied to the plan/addon
tax_id
Optional , default is no tax will be associated
Tax ID to which you would like to associate with this plan.
tax_id
Optional , default is no tax will be associated
Tax ID to which you would like to associate with this plan.
is_taxable
Applicable for Sales Tax/GST
Optional
Set to true if plan must be tax inclusive.
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.
description
Optional
Short description regarding the plan.

Delete a plan

Delete an existing plan. A plan can only be deleted if it has no transactions associated with it.

DELETE /plans/{plan_code}

Request Example

  
$ curl https://subscriptions.zoho.com/api/v1/plans/{plan_code} -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "X-com-zoho-subscriptions-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The plan has been deleted." }

List all plans

List of all plans created.

GET /plans

Request Example

  
$ curl https://subscriptions.zoho.com/api/v1/plans -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "X-com-zoho-subscriptions-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "plans": [ { "plan_code": "basic-monthly", "name": "Basic", "recurring_price": 400, "interval": 1, "interval_unit": "months", "billing_cycles": -1, "trial_period": 0, "setup_fee": 0, "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.", "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" }, {...}, {...} ] }

List of all plans of a product

List of all plans created for a particular product.

GET plans?product_id={product_id}

Request Example

  
$ curl https://subscriptions.zoho.com/api/v1plans?product_id={product_id} -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "X-com-zoho-subscriptions-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "plans": [ { "plan_code": "basic-monthly", "name": "Basic", "description": "Basic monthly plan.", "status": "active", "product_id": "903000000045027", "account_id": "903000987009900", "account_name": "903000000045027", "trial_period": 0, "setup_fee": 0, "recurring_price": 400, "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" } ], "addons": [ { "addon_code": "Email-basic", "name": "Basic" } ], "created_time": "2016-06-05T17:40:49-0700", "updated_time": "2016-06-05T24:40:49-0700" }, {...}, {...} ] }

Mark as active

Change the status of the plan to active.

POST /plans/{plan_code}/markasactive

Request Example

  
$ curl https://subscriptions.zoho.com/api/v1/plans/{plan_code}/markasactive -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "X-com-zoho-subscriptions-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The plan has been marked as active." }

Mark as inactive

Change the status of the plan to inactive.

POST /plans/{plan_code}/markasinactive

Request Example

  
$ curl https://subscriptions.zoho.com/api/v1/plans/{plan_code}/markasinactive -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "X-com-zoho-subscriptions-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The plan has been marked as 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.

Example

{ "addon_code": "Mail-basic", "name": "Email addon", "unit_name": "Email", "pricing_scheme": "unit", "price_brackets": [ { "start_quantity": 1, "end_quantity": 50, "price": 10 } ], "type": "recurring", "interval_unit": "monthly", "applicable_to_all_plans": false, "plans": [ { "plan_code": "basic-monthly", "name": "Email addon" } ], "status": "active", "product_id": "903000000045027", "description": "The addon for additonal email support", "hsn_or_sac": "74191010", "item_tax_preferences": [ { "tax_specification": "intra", "tax_name": "GST", "tax_percentage": 10, "tax_id": "903000000065300" } ], "tax_id": "903000000065300", "created_time": "2016-06-05T18:02:26-0700", "updated_time": "2016-06-05T18:02:26-0700" }

Attribute

addon_code
string
Unique string of your choice which lets you identify this addon.
name
string
Name of your choice to be displayed in the interface and invoices.
unit_name
string
A name of your choice to refer to one unit of the addon.
pricing_scheme
string
Pricing type of the addon can be changed and the values are unit, volume, tier or package. To know more about pricing schemes click here.
price_brackets
list
Array of objects which contains the start quantity, end quantity and price
start_quantity
integer
Lower limit of the addon range.
end_quantity
integer
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.
type
string
Indicates type of the addon. This could be either recurring or one_time.
interval_unit
string
The billing frequency of the addon only if type is recurring and the values can be monthly or yearly.
applicable_to_all_plans
boolean
If the addon is to be associated with all plans, applicable_to_all_plans is set to true; otherwise, it is set to false.
list
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.
plan_code
string
The plan code of the plan to which the addon is to be applied.
name
string
Name of your choice to be displayed in the interface and invoices.
status
string
Status of the addon. It can either be active or inactive.
product_id
string
Product ID to which you want to associate this addon with.
description
string
Short description regarding the addon.
hsn_or_sac
Applicable for India GST
string
HSN or SAC code for Goods/Services addon
item_tax_preferences
Applicable for India GST
list
Tax preferenece for addon
tax_specification
string
Tax specification for the addon. 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
Tax ID to which you would like to associate with this addon.
tax_id
string
Tax ID to which you would like to associate with this addon.
created_time
string
Time at which the addon was created.
updated_time
string
Time at which the addon details were last updated.

Create an addon of unit type

Create a new addon.

POST /addons

Request Example

  
$ curl https://subscriptions.zoho.com/api/v1/addons -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "X-com-zoho-subscriptions-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8" -d '{ "addon_code": "Mail-basic", "name": "Email addon", "unit_name": "Email", "pricing_scheme": "unit", "price_brackets": [ { "price": 10 } ], "type": "recurring", "interval_unit": "monthly", "applicable_to_all_plans": false, "plans": [ { "plan_code": "basic-monthly" } ], "product_id": "903000000045027", "description": "The addon for additonal email support", "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", "tax_exemption_id": "903000006345", "tax_exemption_code": "GST FREE" }

Response Example

  
HTTP/1.1 201 Created Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The addon has been created", "addon": { "addon_code": "Mail-basic", "name": "Email addon", "unit_name": "Email", "pricing_scheme": "unit", "price_brackets": [ { "price": 10 } ], "type": "recurring", "interval_unit": "monthly", "hsn_or_sac": "74191010", "item_tax_preferences": [ { "tax_specification": "intra", "tax_name": "GST", "tax_percentage": 10, "tax_id": "903000000065300" } ], "applicable_to_all_plans": false, "plans": [ { "plan_code": "basic-monthly", "name": "Email addon" } ], "status": "active", "product_id": "903000000045027", "description": "The addon for additonal email support", "tax_id": "903000000065300", "product_type": "goods", "created_time": "2016-06-05T18:02:26-0700", "updated_time": "2016-06-05T18:02:26-0700" } }

ARGUMENTS

addon_code
Required
Unique string of your choice which lets you identify this addon.
name
Required
Name of your choice to be displayed in the interface and invoices.
unit_name
Required
A name of your choice to refer to one unit of the addon.
pricing_scheme
Optional
Pricing type of the addon can be changed and the values are unit, volume, tier or package. To know more about pricing schemes click here.
price_brackets
Required
Array of objects which contains the start quantity, end quantity and price
price
Required
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.
type
Optional , default is recurring
Indicates type of the addon. This could be either recurring or one_time.
interval_unit
Optional , default is monthly
The billing frequency of the addon only if type is recurring and the values can be monthly or yearly.
applicable_to_all_plans
Optional , default is true
If the addon is to be associated with all plans, applicable_to_all_plans is set to true; otherwise, it is set to false.
Required if applicable_to_all_plans is false.
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.
plan_code
Required
The plan code of the plan to which the addon is to be applied.
product_id
Required
Product ID to which you want to associate this addon with.
description
Optional
Short description regarding the addon.
product_type
Applicable for VAT/India GST
Optional
Product type for UK Edition.
hsn_or_sac
Applicable for India GST
Optional
HSN or SAC code for Goods/Services addon
item_tax_preferences
Applicable for India GST
Optional
Tax preferenece for addon
tax_specification
Optional
Tax specification for the addon. It can be either inter or intra.
tax_name
Optional
Name of the tax to which subscription is associated.
tax_percentage
Optional
Percentage of tax applied to the plan/addon
tax_id
Optional , default is no tax will be associated
Tax ID to which you would like to associate with this addon.
tax_id
Optional , default is no tax will be associated
Tax ID to which you would like to associate with this addon.
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.
hsn_or_sac
Applicable for India GST
Optional
HSN or SAC code for Goods/Services addon
item_tax_preferences
Applicable for India GST
Optional
Tax preferenece for addon
tax_specification
Optional
Tax specification for the addon. It can be either inter or intra.
tax_name
Optional
Name of the tax to which subscription is associated.
tax_percentage
Optional
Percentage of tax applied to the plan/addon
tax_id
Optional , default is no tax will be associated
Tax ID to which you would like to associate with this addon.

Create an addon of tier type

Create a new addon.

POST /addons

Request Example

  
$ curl https://subscriptions.zoho.com/api/v1/addons -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "X-com-zoho-subscriptions-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8" -d '{ "addon_code": "Mail-basic", "name": "Email addon", "unit_name": "Email", "pricing_scheme": "tier", "price_brackets": [ { "start_quantity": 1, "end_quantity": 50, "price": 10 } ], "type": "recurring", "interval_unit": "monthly", "applicable_to_all_plans": false, "plans": [ { "plan_code": "basic-monthly" } ], "product_id": "903000000045027", "description": "The addon for additonal email support", "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" } ], "tax_exemption_id": "903000006345", "tax_exemption_code": "GST FREE" }

Response Example

  
HTTP/1.1 201 Created Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The addon has been created", "addon": { "addon_code": "Mail-basic", "name": "Email addon", "unit_name": "Email", "pricing_scheme": "tier", "price_brackets": [ { "start_quantity": 1, "end_quantity": 50, "price": 10 } ], "type": "recurring", "interval_unit": "monthly", "applicable_to_all_plans": false, "plans": [ { "plan_code": "basic-monthly", "name": "Email addon" } ], "status": "active", "product_id": "903000000045027", "description": "The addon for additonal email support", "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-05T18:02:26-0700", "updated_time": "2016-06-05T18:02:26-0700" } }

ARGUMENTS

addon_code
Required
Unique string of your choice which lets you identify this addon.
name
Required
Name of your choice to be displayed in the interface and invoices.
unit_name
Required
A name of your choice to refer to one unit of the addon.
pricing_scheme
Optional
Pricing type of the addon can be changed and the values are unit, volume, tier or package. To know more about pricing schemes click here.
price_brackets
Required
Array of objects which contains the start quantity, end quantity and price
start_quantity
Required for “volume” and “tier” pricing schemes.
Lower limit of the addon range.
end_quantity
Required for “volume”, “tier” and “package” pricing schemes.
Upper limit of the addon range.
price
Required
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.
type
Optional , default is recurring
Indicates type of the addon. This could be either recurring or one_time.
interval_unit
Optional , default is monthly
The billing frequency of the addon only if type is recurring and the values can be monthly or yearly.
applicable_to_all_plans
Optional , default is true
If the addon is to be associated with all plans, applicable_to_all_plans is set to true; otherwise, it is set to false.
Required if applicable_to_all_plans is false.
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.
plan_code
Required
The plan code of the plan to which the addon is to be applied.
product_id
Required
Product ID to which you want to associate this addon with.
description
Optional
Short description regarding the addon.
tax_id
Optional , default is no tax will be associated
Tax ID to which you would like to associate with this addon.
product_type
Applicable for VAT/India GST
Optional
Product type for UK Edition.
hsn_or_sac
Applicable for India GST
Optional
HSN or SAC code for Goods/Services addon
item_tax_preferences
Applicable for India GST
Optional
Tax preferenece for addon
tax_specification
Optional
Tax specification for the addon. It can be either inter or intra.
tax_name
Optional
Name of the tax to which subscription is associated.
tax_percentage
Optional
Percentage of tax applied to the plan/addon
tax_id
Optional , default is no tax will be associated
Tax ID to which you would like to associate with this addon.
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.

Create an addon of volume type

Create a new addon.

POST /addons

Request Example

  
$ curl https://subscriptions.zoho.com/api/v1/addons -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "X-com-zoho-subscriptions-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8" -d '{ "addon_code": "Mail-basic", "name": "Email addon", "unit_name": "Email", "pricing_scheme": "volume", "price_brackets": [ { "start_quantity": 1, "end_quantity": 50, "price": 10 } ], "type": "recurring", "interval_unit": "monthly", "applicable_to_all_plans": false, "plans": [ { "plan_code": "basic-monthly" } ], "product_id": "903000000045027", "description": "The addon for additonal email support", "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", "tax_exemption_id": "903000006345", "tax_exemption_code": "GST FREE" }

Response Example

  
HTTP/1.1 201 Created Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The addon has been created", "addon": { "addon_code": "Mail-basic", "name": "Email addon", "unit_name": "Email", "pricing_scheme": "volume", "price_brackets": [ { "start_quantity": 1, "end_quantity": 50, "price": 10 } ], "type": "recurring", "interval_unit": "monthly", "applicable_to_all_plans": false, "plans": [ { "plan_code": "basic-monthly", "name": "Email addon" } ], "status": "active", "product_id": "903000000045027", "description": "The addon for additonal email support", "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-05T18:02:26-0700", "updated_time": "2016-06-05T18:02:26-0700" } }

ARGUMENTS

addon_code
Required
Unique string of your choice which lets you identify this addon.
name
Required
Name of your choice to be displayed in the interface and invoices.
unit_name
Required
A name of your choice to refer to one unit of the addon.
pricing_scheme
Optional
Pricing type of the addon can be changed and the values are unit, volume, tier or package. To know more about pricing schemes click here.
price_brackets
Required
Array of objects which contains the start quantity, end quantity and price
start_quantity
Required for “volume” and “tier” pricing schemes.
Lower limit of the addon range.
end_quantity
Required for “volume”, “tier” and “package” pricing schemes.
Upper limit of the addon range.
price
Required
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.
type
Optional , default is recurring
Indicates type of the addon. This could be either recurring or one_time.
interval_unit
Optional , default is monthly
The billing frequency of the addon only if type is recurring and the values can be monthly or yearly.
applicable_to_all_plans
Optional , default is true
If the addon is to be associated with all plans, applicable_to_all_plans is set to true; otherwise, it is set to false.
Required if applicable_to_all_plans is false.
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.
plan_code
Required
The plan code of the plan to which the addon is to be applied.
product_id
Required
Product ID to which you want to associate this addon with.
description
Optional
Short description regarding the addon.
product_type
Applicable for VAT/India GST
Optional
Product type for UK Edition.
hsn_or_sac
Applicable for India GST
Optional
HSN or SAC code for Goods/Services addon
item_tax_preferences
Applicable for India GST
Optional
Tax preferenece for addon
tax_specification
Optional
Tax specification for the addon. It can be either inter or intra.
tax_name
Optional
Name of the tax to which subscription is associated.
tax_percentage
Optional
Percentage of tax applied to the plan/addon
tax_id
Optional , default is no tax will be associated
Tax ID to which you would like to associate with this addon.
tax_id
Optional , default is no tax will be associated
Tax ID to which you would like to associate with this addon.
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.

Create an addon of package type

Create a new addon.

POST /addons

Request Example

  
$ curl https://subscriptions.zoho.com/api/v1/addons -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "X-com-zoho-subscriptions-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8" -d '{ "addon_code": "Mail-basic", "name": "Email addon", "unit_name": "Email", "pricing_scheme": "package", "price_brackets": [ { "end_quantity": 50, "price": 10 } ], "type": "recurring", "interval_unit": "monthly", "applicable_to_all_plans": false, "plans": [ { "plan_code": "basic-monthly" } ], "product_id": "903000000045027", "description": "The addon for additonal email support", "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", "tax_exemption_id": "903000006345", "tax_exemption_code": "GST FREE" }

Response Example

  
HTTP/1.1 201 Created Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The addon has been created", "addon": { "addon_code": "Mail-basic", "name": "Email addon", "unit_name": "Email", "pricing_scheme": "package", "price_brackets": [ { "start_quantity": 1, "end_quantity": 50, "price": 10 } ], "type": "recurring", "interval_unit": "monthly", "applicable_to_all_plans": false, "plans": [ { "plan_code": "basic-monthly", "name": "Email addon" } ], "status": "active", "product_id": "903000000045027", "description": "The addon for additonal email support", "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", "created_time": "2016-06-05T18:02:26-0700", "updated_time": "2016-06-05T18:02:26-0700" } }

ARGUMENTS

addon_code
Required
Unique string of your choice which lets you identify this addon.
name
Required
Name of your choice to be displayed in the interface and invoices.
unit_name
Required
A name of your choice to refer to one unit of the addon.
pricing_scheme
Optional
Pricing type of the addon can be changed and the values are unit, volume, tier or package. To know more about pricing schemes click here.
price_brackets
Required
Array of objects which contains the start quantity, end quantity and price
end_quantity
Required for “volume”, “tier” and “package” pricing schemes.
Upper limit of the addon range.
price
Required
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.
type
Optional , default is recurring
Indicates type of the addon. This could be either recurring or one_time.
interval_unit
Optional , default is monthly
The billing frequency of the addon only if type is recurring and the values can be monthly or yearly.
applicable_to_all_plans
Optional , default is true
If the addon is to be associated with all plans, applicable_to_all_plans is set to true; otherwise, it is set to false.
Required if applicable_to_all_plans is false.
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.
plan_code
Required
The plan code of the plan to which the addon is to be applied.
product_id
Required
Product ID to which you want to associate this addon with.
description
Optional
Short description regarding the addon.
product_type
Applicable for VAT/India GST
Optional
Product type for UK Edition.
hsn_or_sac
Applicable for India GST
Optional
HSN or SAC code for Goods/Services addon
item_tax_preferences
Applicable for India GST
Optional
Tax preferenece for addon
tax_specification
Optional
Tax specification for the addon. It can be either inter or intra.
tax_name
Optional
Name of the tax to which subscription is associated.
tax_percentage
Optional
Percentage of tax applied to the plan/addon
tax_id
Optional , default is no tax will be associated
Tax ID to which you would like to associate with this addon.
tax_id
Optional , default is no tax will be associated
Tax ID to which you would like to associate with this addon.
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.

Retrieve an addon

Details for an existing Addon.

GET /addons/{addon_code}

Request Example

  
$ curl https://subscriptions.zoho.com/api/v1/addons/{addon_code} -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "X-com-zoho-subscriptions-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "addon": { "addon_code": "Mail-basic", "name": "Email addon", "unit_name": "Email", "pricing_scheme": "unit", "price_brackets": [ { "start_quantity": 1, "end_quantity": 50, "price": 10 } ], "type": "recurring", "interval_unit": "monthly", "applicable_to_all_plans": false, "plans": [ { "plan_code": "basic-monthly", "name": "Email addon" } ], "status": "active", "product_id": "903000000045027", "description": "The addon for additonal email support", "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", "created_time": "2016-06-05T18:02:26-0700", "updated_time": "2016-06-05T18:02:26-0700" } }

Update an addon

Update details of an existing addon.

PUT /addons/{addon_code}

Request Example

  
$ curl https://subscriptions.zoho.com/api/v1/addons/{addon_code} -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "X-com-zoho-subscriptions-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8" -d '{ "addon_code": "Mail-basic", "name": "Email addon", "unit_name": "Email", "pricing_scheme": "unit", "price_brackets": [ { "start_quantity": 1, "end_quantity": 50, "price": 10 } ], "type": "recurring", "interval_unit": "monthly", "applicable_to_all_plans": false, "plans": [ { "plan_code": "basic-monthly", "name": "Email addon" } ], "product_id": "903000000045027", "description": "The addon for additonal email support", "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", "tax_exemption_id": "903000006345", "tax_exemption_code": "GST FREE" }

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The addon details have been updated.", "addon": { "addon_code": "Mail-basic", "name": "Email addon", "unit_name": "Email", "pricing_scheme": "unit", "price_brackets": [ { "start_quantity": 1, "end_quantity": 50, "price": 10 } ], "type": "recurring", "interval_unit": "monthly", "applicable_to_all_plans": false, "plans": [ { "plan_code": "basic-monthly", "name": "Email addon" } ], "status": "active", "product_id": "903000000045027", "description": "The addon for additonal email support", "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", "created_time": "2016-06-05T18:02:26-0700", "updated_time": "2016-06-05T18:02:26-0700" } }

ARGUMENTS

addon_code
Required
Unique string of your choice which lets you identify this addon.
name
Required
Name of your choice to be displayed in the interface and invoices.
unit_name
Required
A name of your choice to refer to one unit of the addon.
pricing_scheme
Optional , default is unit
Pricing type of the addon can be changed and the values are unit, volume, tier or package. To know more about pricing schemes click here.
price_brackets
Required
Array of objects which contains the start quantity, end quantity and price
start_quantity
Required for “volume” and “tier” pricing schemes.
Lower limit of the addon range.
end_quantity
Required for “volume”, “tier” and “package” pricing schemes.
Upper limit of the addon range.
price
Required
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.
type
Optional , default is recurring
Indicates type of the addon. This could be either recurring or one_time.
interval_unit
Optional , default is monthly
The billing frequency of the addon only if type is recurring and the values can be monthly or yearly.
applicable_to_all_plans
Optional , default is true
If the addon is to be associated with all plans, applicable_to_all_plans is set to true; otherwise, it is set to false.
Required if applicable_to_all_plans is false.
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.
plan_code
Required
The plan code of the plan to which the addon is to be applied.
name
Required
Name of your choice to be displayed in the interface and invoices.
product_id
Required
Product ID to which you want to associate this addon with.
description
Optional
Short description regarding the addon.
product_type
Applicable for VAT/India GST
Optional
Product type for UK Edition.
hsn_or_sac
Applicable for India GST
Optional
HSN or SAC code for Goods/Services addon
item_tax_preferences
Applicable for India GST
Optional
Tax preferenece for addon
tax_specification
Optional
Tax specification for the addon. It can be either inter or intra.
tax_name
Optional
Name of the tax to which subscription is associated.
tax_percentage
Optional
Percentage of tax applied to the plan/addon
tax_id
Optional , default is no tax will be associated
Tax ID to which you would like to associate with this addon.
tax_id
Optional , default is no tax will be associated
Tax ID to which you would like to associate with this addon.
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.

Delete an addon

Delete an existing addon.

DELETE /addons/{addon_code}

Request Example

  
$ curl https://subscriptions.zoho.com/api/v1/addons/{addon_code} -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "X-com-zoho-subscriptions-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The addon has been deleted." }

List all addons

List of all addons.

GET /addons

Request Example

  
$ curl https://subscriptions.zoho.com/api/v1/addons -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "X-com-zoho-subscriptions-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "addons": [ { "addon_code": "Mail-basic", "name": "Email addon", "unit_name": "Email", "pricing_scheme": "unit", "price_brackets": [ { "start_quantity": 1, "end_quantity": 50, "price": 10 } ], "type": "recurring", "interval_unit": "monthly", "applicable_to_all_plans": false, "status": "active", "product_id": "903000000045027", "description": "The addon for additonal email support", "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", "created_time": "2016-06-05T18:02:26-0700", "updated_time": "2016-06-05T18:02:26-0700" }, {...}, {...} ] }

Mark as active

Change status of the addon to active.

POST /addons/{addon_code}/markasactive

Request Example

  
$ curl https://subscriptions.zoho.com/api/v1/addons/{addon_code}/markasactive -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "X-com-zoho-subscriptions-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The addon has been marked as active." }

Mark as inactive

Change status of the addon to inactive.

POST /addons/{addon_code}/markasinactive

Request Example

  
$ curl https://subscriptions.zoho.com/api/v1/addons/{addon_code}/markasinactive -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "X-com-zoho-subscriptions-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The addon has been marked as inactive." }

Coupons

Coupons are used to provide discounts and special offers to customers. These coupons can be applied to a subscription at any time.

Example

{ "coupon_code": "THANKSGIVING20", "name": "Thanksgiving 20 percent offer", "description": "Twenty percent offer for thanks giving.", "type": "one_time", "status": "active", "discount_by": "percentage", "discount_value": 20, "product_id": "903000000045027", "max_redemption": 50, "redemption_count": 10, "expiry_at": "2016-08-28", "apply_to_plans": "select", "plans": [ { "plan_code": "basic-monthly", "name": "Thanksgiving 20 percent offer" } ], "apply_to_addons": "select", "addons": [ { "addon_code": "Email-basic", "name": "Thanksgiving 20 percent offer" } ], "created_time": "2016-06-05T18:02:26-0700", "updated_time": "2016-06-05T18:02:26-0700" }

Attribute

coupon_code
string
Unique string of your choice which lets you identify this coupon.
name
string
Name of the coupon to be displayed in the interface and invoices.
description
string
A small description about the coupon.
type
string
This indicates whether the coupon is to be applied only once or each time an invoice is raised for the subscription. It can either be one_time or 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
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
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.
addon_code
string
The addon code of the addon to which the coupon is to be applied.
name
string
Name of the coupon to be displayed in the interface and invoices.
created_time
string
Time at which the coupon was created.
updated_time
string
Time at which the coupon details were last updated.

Create an coupon

Create a new coupon.

POST /coupons

Request Example

  
$ curl https://subscriptions.zoho.com/api/v1/coupons -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "X-com-zoho-subscriptions-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8" -d '{ "coupon_code": "THANKSGIVING20", "name": "Thanksgiving 20 percent offer", "description": "Twenty percent offer for thanks giving.", "type": "one_time", "discount_by": "percentage", "discount_value": 20, "product_id": "903000000045027", "max_redemption": 50, "expiry_at": "2016-08-28", "apply_to_plans": "select", "plans": [ { "plan_code": "basic-monthly" } ], "apply_to_addons": "select", "addons": [ { "addon_code": "Email-basic" } ] }

Response Example

  
HTTP/1.1 201 Created Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The coupon has been created", "coupon": { "coupon_code": "THANKSGIVING20", "name": "Thanksgiving 20 percent offer", "description": "Twenty percent offer for thanks giving.", "type": "one_time", "status": "active", "discount_by": "percentage", "discount_value": 20, "product_id": "903000000045027", "max_redemption": 50, "redemption_count": 10, "expiry_at": "2016-08-28", "apply_to_plans": "select", "plans": [ { "plan_code": "basic-monthly", "name": "Thanksgiving 20 percent offer" } ], "apply_to_addons": "select", "addons": [ { "addon_code": "Email-basic", "name": "Thanksgiving 20 percent offer" } ], "created_time": "2016-06-05T18:02:26-0700", "updated_time": "2016-06-05T18:02:26-0700" } }

ARGUMENTS

coupon_code
Required
Unique string of your choice which lets you identify this coupon.
name
Required
Name of the coupon to be displayed in the interface and invoices.
description
Optional
A small description about the coupon.
type
Required
This indicates whether the coupon is to be applied only once or each time an invoice is raised for the subscription. It can either be one_time or forever.
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.
Required if apply_to_plans is 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.
Required if apply_to_addons is 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.
addon_code
Required
The addon code of the addon to which the coupon is to be applied.

Retrieve a coupon

Details of an existing coupon.

GET /coupons/{coupon_code}

Request Example

  
$ curl https://subscriptions.zoho.com/api/v1/coupons/{coupon_code} -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "X-com-zoho-subscriptions-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "coupon": { "coupon_code": "THANKSGIVING20", "name": "Thanksgiving 20 percent offer", "description": "Twenty percent offer for thanks giving.", "type": "one_time", "status": "active", "discount_by": "percentage", "discount_value": 20, "product_id": "903000000045027", "max_redemption": 50, "redemption_count": 10, "expiry_at": "2016-08-28", "apply_to_plans": "select", "plans": [ { "plan_code": "basic-monthly", "name": "Thanksgiving 20 percent offer" } ], "apply_to_addons": "select", "addons": [ { "addon_code": "Email-basic", "name": "Thanksgiving 20 percent offer" } ], "created_time": "2016-06-05T18:02:26-0700", "updated_time": "2016-06-05T18:02:26-0700" } }

Update a coupon

Update details of an existing coupon.

PUT /coupons/{coupon_code}

Request Example

  
$ curl https://subscriptions.zoho.com/api/v1/coupons/{coupon_code} -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "X-com-zoho-subscriptions-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8" -d '{ "name": "Thanksgiving 20 percent offer", "description": "Twenty percent offer for thanks giving.", "max_redemption": 50, "expiry_at": "2016-08-28" }

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The coupon details have been updated.", "coupon": { "coupon_code": "THANKSGIVING20", "name": "Thanksgiving 20 percent offer", "description": "Twenty percent offer for thanks giving.", "type": "one_time", "status": "active", "discount_by": "percentage", "discount_value": 20, "product_id": "903000000045027", "max_redemption": 50, "redemption_count": 10, "expiry_at": "2016-08-28", "apply_to_plans": "select", "plans": [ { "plan_code": "basic-monthly", "name": "Thanksgiving 20 percent offer" } ], "apply_to_addons": "select", "addons": [ { "addon_code": "Email-basic", "name": "Thanksgiving 20 percent offer" } ], "created_time": "2016-06-05T18:02:26-0700", "updated_time": "2016-06-05T18:02:26-0700" } }

ARGUMENTS

name
Required
Name of the coupon to be displayed in the interface and invoices.
description
Optional
A small description about the coupon.
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.

Delete a coupon

Delete an existing coupon.

DELETE /coupons/{coupon_code}

Request Example

  
$ curl https://subscriptions.zoho.com/api/v1/coupons/{coupon_code} -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "X-com-zoho-subscriptions-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The coupon has been deleted." }

List all coupons

List of all coupons.

GET /coupons

Request Example

  
$ curl https://subscriptions.zoho.com/api/v1/coupons -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "X-com-zoho-subscriptions-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "coupons": [ { "coupon_code": "THANKSGIVING20", "name": "Thanksgiving 20 percent offer", "description": "Twenty percent offer for thanks giving.", "type": "one_time", "status": "active", "discount_by": "percentage", "discount_value": 20, "product_id": "903000000045027", "max_redemption": 50, "redemption_count": 10, "expiry_at": "2016-08-28", "created_time": "2016-06-05T18:02:26-0700", "updated_time": "2016-06-05T18:02:26-0700" }, {...}, {...} ] }

Mark as active

status of the coupon will be changed to active.

POST /coupons/{coupon_code}/markasactive

Request Example

  
$ curl https://subscriptions.zoho.com/api/v1/coupons/{coupon_code}/markasactive -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "X-com-zoho-subscriptions-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The coupon has been marked as active." }

Mark as inactive

status of the coupon will be changed to inactive.

POST /coupons/{coupon_code}/markasinactive

Request Example

  
$ curl https://subscriptions.zoho.com/api/v1/coupons/{coupon_code}/markasinactive -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "X-com-zoho-subscriptions-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The coupon has been marked as inactive." }

Customers

A customer object allows you to keep track of all customer related information.

Example

{ "customer_id": "903000000000099", "display_name": "Bowman Furniture", "salutation": "Mr.", "first_name": "Benjamin", "last_name": "George", "email": "benjamin.george@bowmanfurniture.com", "company_name": "Bowman Furniture", "phone": 23467278, "mobile": 938237475, "website": "www.bowmanfurniture.com", "billing_address": { "attention": "Benjamin George", "street": "Harrington Bay Street", "city": "Salt Lake City", "state": "CA", "zip": 92612, "country": "U.S.A", "fax": 4527389 }, "shipping_address": { "attention": "Benjamin George", "street": "Harrington Bay Street", "city": "Salt Lake City", "state": "CA", "zip": 92612, "country": "U.S.A", "fax": 4527389 }, "currency_code": "USD", "currency_id": "90300000000097", "ach_supported": true, "price_precision": 2, "unused_credits": 0, "outstanding": 0, "notes": "Bowman Furniture", "is_portal_enabled": true, "language_code": "en", "status": "active", "custom_fields": [ { "value": 129890, "label": "label", "data_type": "text" } ], "zcrm_account_id": "903000800069001", "zcrm_contact_id": "903000000098214", "updated_time": "2016-06-05T02:30:08-0700", "created_time": "2016-06-05T12:30:08-0700", "source": "user", "payment_terms_label": "Due on receipt", "is_linked_with_zohocrm": false, "primary_contactperson_id": "903000001045003", "can_add_card": true, "can_add_bank_account": true, "default_templates": { "invoice_template_id": "90300000311340", "creditnote_template_id": "90300000232140" } }

Attribute

customer_id
string
Unique ID generated by the server. This is used as identifier.
display_name
string
Name of the customer which will be displayed in the interface and invoices.
salutation
string
Salutation of the customer.
first_name
string
First name of the customer.
last_name
string
Last name of the customer.
email
string
Email address of the customer.
company_name
string
Registered name of the company the customer represents.
phone
string
Customer's landline or fixed-line number.
mobile
string
Customer's mobile phone number.
website
string
Customer's website if any.
billing_address
object
Customer's billing address object. It contains attention,street, city, state,zip,country and .
attention
string
Attention of the customer's billing address.
street
string
Street of the customer's billing address.
city
string
City of the customer's billing address.
state
string
State of the customer's billing address.
zip
string
Zip code of the customer's billing address.
country
string
Country of the customer's billing address.
fax
string
Fax number for the customer's billing address.
shipping_address
object
Customer's shipping address object. It contains attention,street, city, state,zip,country and .
attention
Attention of the customer’s shipping address.
street
Name of the street of the customer’s shipping address.
city
Name of the city of the customer’s shipping address.
state
Name of the state of the customer’s shipping address.
zip
Zip code of the customer’s shipping address.
country
Country code of the customer’s shipping address.
fax
Fax number of the customer’s shipping address.
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
string
Currency ID of the customer's currency.
ach_supported
boolean
Set to true if ACH payment is supported for the customer.
price_precision
integer
The Price Precision of the selected currency for the customer
unused_credits
double
Customer's unused credits.
outstanding
double
Amount that has to be paid to the customer.
notes
string
A short note about the customer.
is_portal_enabled
boolean
Is Client portal enabled for the customer.
language_code
Client portal language for the customer
status
string
Status of the customer. It can either be active or inactive.
custom_fields
list
Additional fields for customers.
value
string
Value of the custom field.
label
string
Label of the custom field.
data_type
string
Data type of the custom field.
zcrm_account_id
string
This is the Zoho CRM account id of the customer if the customer is synced with the accounts in Zoho CRM.
zcrm_contact_id
string
This is the Zoho CRM contact id of the customer if the customer is synced with the contacts in Zoho CRM.
updated_time
string
Time at which the customer details were last updated.
created_time
string
Time at which the customer was created.
source
string
Denotes how the customer was created.
payment_terms_label
string
Text field of payment terms.
is_linked_with_zohocrm
boolean
Set to true if linked with Zoho CRM.
primary_contactperson_id
string
Unique Id of primary contact person. This ID will refer to contactperson_id for this customer.
can_add_card
boolean
Set to true if card can be associated.
can_add_bank_account
boolean
Set to true if bank account can be associated.
default_templates
object
Default templates associated with the customer.
invoice_template_id
string
Unique Id used to denote the invoice template.
creditnote_template_id
string
Unique Id used to denote the credit note template.

Create a customer

A new customer can a be created separately as well as at the time of creation of a new subscription.

POST /customers

Request Example

  
$ curl https://subscriptions.zoho.com/api/v1/customers -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "X-com-zoho-subscriptions-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8" -d '{ "display_name": "Bowman Furniture", "salutation": "Mr.", "first_name": "Benjamin", "last_name": "George", "email": "benjamin.george@bowmanfurniture.com", "company_name": "Bowman Furniture", "phone": 23467278, "mobile": 938237475, "department": "Marketing", "designation": "Evangelist", "website": "www.bowmanfurniture.com", "billing_address": { "attention": "Benjamin George", "street": "Harrington Bay Street", "city": "Salt Lake City", "state": "CA", "zip": 92612, "country": "U.S.A", "fax": 4527389 }, "shipping_address": { "attention": "Benjamin George", "street": "Harrington Bay Street", "city": "Salt Lake City", "state": "CA", "zip": 92612, "country": "U.S.A", "fax": 4527389 }, "payment_terms": 5, "payment_terms_label": "Due on receipt", "currency_code": "USD", "ach_supported": true, "twitter": "BowmanFurniture", "facebook": "BowmanFurniture", "skype": "Bowman Furniture", "notes": "Bowman Furniture", "gst_no": "33AAAAA0000A1Z5", "gst_treatment": "business_gst", "place_of_contact": "TN", "vat_treatment": "non_eu", "vat_reg_no": 51423456782, "country_code": "DE", "is_taxable": true, "tax_id": "903000002345", "tax_authority_name": "ATO", "tax_exemption_id": "903000006345", "tax_exemption_code": "GST FREE", "default_templates": { "invoice_template_id": "90300000311340", "creditnote_template_id": "90300000232140" } }

Response Example

  
HTTP/1.1 201 Created Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The customer has been created", "customer": { "customer_id": "903000000000099", "display_name": "Bowman Furniture", "salutation": "Mr.", "first_name": "Benjamin", "last_name": "George", "email": "benjamin.george@bowmanfurniture.com", "company_name": "Bowman Furniture", "phone": 23467278, "mobile": 938237475, "website": "www.bowmanfurniture.com", "department": "Marketing", "designation": "Evangelist", "billing_address": { "attention": "Benjamin George", "street": "Harrington Bay Street", "city": "Salt Lake City", "state": "CA", "zip": 92612, "country": "U.S.A", "fax": 4527389 }, "shipping_address": { "attention": "Benjamin George", "street": "Harrington Bay Street", "city": "Salt Lake City", "state": "CA", "zip": 92612, "country": "U.S.A", "fax": 4527389 }, "currency_code": "USD", "currency_id": "90300000000097", "ach_supported": true, "twitter": "BowmanFurniture", "facebook": "BowmanFurniture", "skype": "Bowman Furniture", "notes": "Bowman Furniture", "gst_no": "33AAAAA0000A1Z5", "gst_treatment": "business_gst", "place_of_contact": "TN", "price_precision": 2, "unused_credits": 0, "outstanding": 0, "status": "active", "custom_fields": [ { "index": 1, "value": 129890, "data_type": "text", "label": "label" } ], "zcrm_account_id": "903000800069001", "zcrm_contact_id": "903000000098214", "updated_time": "2016-06-05T02:30:08-0700", "created_time": "2016-06-05T12:30:08-0700", "source": "user", "payment_terms": 5, "payment_terms_label": "Due on receipt", "is_linked_with_zohocrm": false, "primary_contactperson_id": "903000001045003", "can_add_card": true, "can_add_bank_account": true, "default_templates": { "invoice_template_id": "90300000311340", "creditnote_template_id": "90300000232140" } } }

ARGUMENTS

display_name
Required
Name of the customer which will be displayed in the interface and invoices.
salutation
Optional
Salutation of the customer.
first_name
Optional
First name of the customer.
last_name
Optional
Last name of the customer.
email
Required
Email address of the customer.
company_name
Optional
Registered name of the company the customer represents.
phone
Optional
Customer's landline or fixed-line number.
mobile
Optional
Customer's mobile phone number.
department
Optional
Customer's department.
designation
Optional
Customer's designation.
website
Optional
Customer's website if any.
billing_address
Optional
Customer's billing address object. It contains attention,street, city, state,zip,country and .
attention
Optional
Attention of the customer's billing address.
street
Optional
Street of the customer's billing address.
city
Optional
City of the customer's billing address.
state
Optional
State of the customer's billing address.
zip
Optional
Zip code of the customer's billing address.
country
Optional
Country of the customer's billing address.
fax
Optional
Fax number for the customer's billing address.
shipping_address
Optional
Customer's shipping address object. It contains attention,street, city, state,zip,country and .
attention
Optional
Attention of the customer’s shipping address.
street
Optional
Name of the street of the customer’s shipping address.
city
Optional
Name of the city of the customer’s shipping address.
state
Optional
Name of the state of the customer’s shipping address.
zip
Optional
Zip code of the customer’s shipping address.
country
Optional
Country code of the customer’s shipping address.
fax
Optional
Fax number of the customer’s shipping address.
payment_terms
Optional
Net payment term for the customer.
payment_terms_label
Optional
Text field of payment terms.
currency_code
Optional , default is currency_code chosen in organization profile settings
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.
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, overseas
business_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.
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.
default_templates
Optional
Default templates associated with the customer.
invoice_template_id
Optional
Unique Id used to denote the invoice template.
creditnote_template_id
Optional
Unique Id used to denote the credit note template.

Retrieve a customer

Details of an existing customer.

GET /customers/{customer_id}

Request Example

  
$ curl https://subscriptions.zoho.com/api/v1/customers/{customer_id} -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "X-com-zoho-subscriptions-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "customer": { "customer_id": "903000000000099", "display_name": "Bowman Furniture", "salutation": "Mr.", "first_name": "Benjamin", "last_name": "George", "email": "benjamin.george@bowmanfurniture.com", "company_name": "Bowman Furniture", "phone": 23467278, "mobile": 938237475, "website": "www.bowmanfurniture.com", "designation": "Evangelist", "department": "Marketing", "billing_address": { "attention": "Benjamin George", "street": "Harrington Bay Street", "city": "Salt Lake City", "state": "CA", "zip": 92612, "country": "U.S.A", "fax": 4527389 }, "shipping_address": { "attention": "Benjamin George", "street": "Harrington Bay Street", "city": "Salt Lake City", "state": "CA", "zip": 92612, "country": "U.S.A", "fax": 4527389 }, "currency_code": "USD", "currency_id": "90300000000097", "ach_supported": true, "gst_no": "33AAAAA0000A1Z5", "gst_treatment": "business_gst", "place_of_contact": "TN", "price_precision": 2, "unused_credits": 0, "outstanding": 0, "notes": "Bowman Furniture", "status": "active", "custom_fields": [ { "index": 1, "value": 129890, "data_type": "text", "label": "label" } ], "zcrm_account_id": "903000800069001", "zcrm_contact_id": "903000000098214", "updated_time": "2016-06-05T02:30:08-0700", "created_time": "2016-06-05T12:30:08-0700", "source": "user", "payment_terms_label": "Due on receipt", "is_linked_with_zohocrm": false, "primary_contactperson_id": "903000001045003", "can_add_card": true, "can_add_bank_account": true, "default_templates": { "invoice_template_id": "90300000311340", "creditnote_template_id": "90300000232140" } } }

Update a customer

Update details of an existing customer.

PUT /customers/{customer_id}

Request Example

  
$ curl https://subscriptions.zoho.com/api/v1/customers/{customer_id} -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "X-com-zoho-subscriptions-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8" -d '{ "display_name": "Bowman Furniture", "salutation": "Mr.", "first_name": "Benjamin", "last_name": "George", "email": "benjamin.george@bowmanfurniture.com", "company_name": "Bowman Furniture", "phone": 23467278, "mobile": 938237475, "billing_address": { "attention": "Benjamin George", "street": "Harrington Bay Street", "city": "Salt Lake City", "state": "CA", "zip": 92612, "country": "U.S.A", "fax": 4527389 }, "shipping_address": { "attention": "Benjamin George", "street": "Harrington Bay Street", "city": "Salt Lake City", "state": "CA", "zip": 92612, "country": "U.S.A", "fax": 4527389 }, "fax": 4527389, "currency_code": "USD", "twitter": "BowmanFurniture", "facebook": "BowmanFurniture", "skype": "Bowman Furniture", "gst_no": "33AAAAA0000A1Z5", "gst_treatment": "business_gst", "place_of_contact": "TN", "vat_treatment": "non_eu", "vat_reg_no": 51423456782, "country_code": "DE", "is_taxable": true, "tax_id": "903000002345", "tax_authority_id": "903000006345", "tax_authority_name": "ATO", "tax_exemption_id": "903000006345", "tax_exemption_code": "GST FREE", "default_templates": { "invoice_template_id": "90300000311340", "creditnote_template_id": "90300000232140" } }

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The customer details have been updated.", "customer": { "customer_id": "903000000000099", "display_name": "Bowman Furniture", "salutation": "Mr.", "first_name": "Benjamin", "last_name": "George", "email": "benjamin.george@bowmanfurniture.com", "company_name": "Bowman Furniture", "phone": 23467278, "mobile": 938237475, "website": "www.bowmanfurniture.com", "department": "Marketing", "designation": "Evangelist", "billing_address": { "attention": "Benjamin George", "street": "Harrington Bay Street", "city": "Salt Lake City", "state": "CA", "zip": 92612, "country": "U.S.A", "fax": 4527389 }, "shipping_address": { "attention": "Benjamin George", "street": "Harrington Bay Street", "city": "Salt Lake City", "state": "CA", "zip": 92612, "country": "U.S.A", "fax": 4527389 }, "currency_code": "USD", "currency_id": "90300000000097", "ach_supported": true, "price_precision": 2, "unused_credits": 0, "outstanding": 0, "notes": "Bowman Furniture", "status": "active", "custom_fields": [ { "index": 1, "value": 129890, "label": "label", "data_type": "text" } ], "zcrm_account_id": "903000800069001", "zcrm_contact_id": "903000000098214", "updated_time": "2016-06-05T02:30:08-0700", "created_time": "2016-06-05T12:30:08-0700", "source": "user", "payment_terms_label": "Due on receipt", "is_linked_with_zohocrm": false, "primary_contactperson_id": "903000001045003", "can_add_card": true, "can_add_bank_account": true, "default_templates": [ { "invoice_template_id": "90300000311340", "creditnote_template_id": "90300000232140" } ] } }

ARGUMENTS

display_name
Required
Name of the customer which will be displayed in the interface and invoices.
salutation
Optional
Salutation of the customer.
first_name
Optional
First name of the customer.
last_name
Optional
Last name of the customer.
email
Required
Email address of the customer.
company_name
Optional
Registered name of the company the customer represents.
phone
Optional
Customer's landline or fixed-line number.
mobile
Optional
Customer's mobile phone number.
billing_address
Optional
Customer's billing address object. It contains attention,street, city, state,zip,country and .
attention
Optional
Attention of the customer's billing address.
street
Optional
Street of the customer's billing address.
city
Optional
City of the customer's billing address.
state
Optional
State of the customer's billing address.
zip
Optional
Zip code of the customer's billing address.
country
Optional
Country of the customer's billing address.
fax
Optional
Fax number for the customer's billing address.
shipping_address
Optional
Customer's shipping address object. It contains attention,street, city, state,zip,country and .
attention
Optional
Attention of the customer’s shipping address.
street
Optional
Name of the street of the customer’s shipping address.
city
Optional
Name of the city of the customer’s shipping address.
state
Optional
Name of the state of the customer’s shipping address.
zip
Optional
Zip code of the customer’s shipping address.
country
Optional
Country code of the customer’s shipping address.
fax
Optional
Fax number of the customer’s shipping address.
fax
Optional
Fax number for the customer's billing address.
currency_code
Optional , default is currency_code chosen in organization profile settings
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
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, overseas
business_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.
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.
default_templates
Optional
Default templates associated with the customer.
invoice_template_id
Optional
Unique Id used to denote the invoice template.
creditnote_template_id
Optional
Unique Id used to denote the credit note template.

Delete a customer

Delete an existing customer.

DELETE /customers/{customer_id}

Request Example

  
$ curl https://subscriptions.zoho.com/api/v1/customers/{customer_id} -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "X-com-zoho-subscriptions-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The customer has been deleted." }

List all customers

List of all customers.

GET /customers

Request Example

  
$ curl https://subscriptions.zoho.com/api/v1/customers -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "X-com-zoho-subscriptions-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "customers": [ { "customer_id": "903000000000099", "display_name": "Bowman Furniture", "salutation": "Mr.", "first_name": "Benjamin", "last_name": "George", "email": "benjamin.george@bowmanfurniture.com", "company_name": "Bowman Furniture", "phone": 23467278, "mobile": 938237475, "website": "www.bowmanfurniture.com", "department": "Marketing", "designation": "Evangelist", "currency_code": "USD", "unused_credits": 0, "outstanding": 0, "is_gapps_customer": false, "updated_time": "2016-06-05T02:30:08-0700", "created_time": "2016-06-05T12:30:08-0700" }, {...}, {...} ] }

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

Request Example

  
$ curl https://subscriptions.zoho.com/api/v1/transactions?filter_by=TransactionType.All -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "X-com-zoho-subscriptions-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "customers": [ { "transaction_id": "903000000094534", "reference_id": "903000000021976", "date": "2016-09-30", "type": "invoice", "status": "active", "amount": "20.50" }, {...}, {...} ] }

Mark as active

Change status of the customer to active.

POST /customers/{customer_id}/markasactive

Request Example

  
$ curl https://subscriptions.zoho.com/api/v1/customers/{customer_id}/markasactive -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "X-com-zoho-subscriptions-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The customer has been marked as active." }

Mark as inactive

Change status of the customer to inactive. A cutomer can be marked as inactive only if there is no active subscription associated with the customer.

POST /customers/{customer_id}/markasinactive

Request Example

  
$ curl https://subscriptions.zoho.com/api/v1/customers/{customer_id}/markasinactive -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "X-com-zoho-subscriptions-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The customer has been marked as inactive." }

Contact-Persons

A contact person is customer’s additional point of contact.

Example

{ "contactperson_id": "903000000053362", "first_name": "Mark", "last_name": "Cruizer", "email": "mark.cruzer@bowmanfurniture.com", "mobile": "786663728", "phone": "0417254482", "customer_id": "903000000000099", "created_time": "2016-06-05T12:30:08-0700", "updated_time": "2016-06-05T02:30:08-0700" }

Attribute

contactperson_id
string
Unique ID generated by the server.This can be used as an identifier.
first_name
string
First name of the contact person.
last_name
string
Last name of the contact person.
email
string
Email ID of the contact person to whom notifications regarding the subscription needs to be sent.
mobile
string
Mobile number of the contact person.
phone
string
Landline or fixed line number of the contact person.
customer_id
string
Customer ID of the customer the contact person is associated with.
created_time
string
Time at which the contact person was created.
updated_time
string
Time at which the contact person details were last updated.

Create a contact person

Create a new contact person.

POST /customers/{customer_id}/contactpersons

Request Example

  
$ curl https://subscriptions.zoho.com/api/v1/customers/{customer_id}/contactpersons -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "X-com-zoho-subscriptions-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8" -d '{ "first_name": "Mark", "last_name": "Cruizer", "email": "mark.cruzer@bowmanfurniture.com", "mobile": "786663728", "phone": "0417254482", "fax": 4527389 }

Response Example

  
HTTP/1.1 201 Created Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The contactperson has been Created", "contact_person": { "contactperson_id": "903000000053362", "first_name": "Mark", "last_name": "Cruizer", "email": "mark.cruzer@bowmanfurniture.com", "mobile": "786663728", "phone": "0417254482", "fax": 4527389, "customer_id": "903000000000099", "created_time": "2016-06-05T12:30:08-0700", "updated_time": "2016-06-05T02:30:08-0700" } }

ARGUMENTS

first_name
Optional
First name of the contact person.
last_name
Optional
Last name of the contact person.
email
Required
Email ID of the contact person to whom notifications regarding the subscription needs to be sent.
mobile
Optional
Mobile number of the contact person.
phone
Optional
Landline or fixed line number of the contact person.
fax
Optional
Customer's fax number.

Retrieve a contact person

Details of an existing contact person.

GET /customers/{customer_id}/contactpersons/{contactperson_id}

Request Example

  
$ curl https://subscriptions.zoho.com/api/v1/customers/{customer_id}/contactpersons/{contactperson_id} -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "X-com-zoho-subscriptions-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "contact_person": { "contactperson_id": "903000000053362", "first_name": "Mark", "last_name": "Cruizer", "email": "mark.cruzer@bowmanfurniture.com", "mobile": "786663728", "phone": "0417254482", "fax": 4527389, "customer_id": "903000000000099", "created_time": "2016-06-05T12:30:08-0700", "updated_time": "2016-06-05T02:30:08-0700" } }

Update a contact person

Update the details of an existing contact person.

PUT /customers/{customer_id}/contactpersons/{contactperson_id}

Request Example

  
$ curl https://subscriptions.zoho.com/api/v1/customers/{customer_id}/contactpersons/{contactperson_id} -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "X-com-zoho-subscriptions-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8" -d '{ "first_name": "Mark", "last_name": "Cruizer", "email": "mark.cruzer@bowmanfurniture.com", "mobile": "786663728", "phone": "0417254482", "created_time": "2016-06-05T12:30:08-0700", "updated_time": "2016-06-05T02:30:08-0700" }

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The contactperson details has been updated.", "contact_person": { "contactperson_id": "903000000053362", "first_name": "Mark", "last_name": "Cruizer", "email": "mark.cruzer@bowmanfurniture.com", "mobile": "786663728", "phone": "0417254482", "fax": 4527389, "customer_id": "903000000000099", "created_time": "2016-06-05T12:30:08-0700", "updated_time": "2016-06-05T02:30:08-0700" } }

ARGUMENTS

first_name
Optional
First name of the contact person.
last_name
Optional
Last name of the contact person.
email
Required
Email ID of the contact person to whom notifications regarding the subscription needs to be sent.
mobile
Optional
Mobile number of the contact person.
phone
Optional
Landline or fixed line number of the contact person.
created_time
Optional
Time at which the contact person was created.
updated_time
Optional
Time at which the contact person details were last updated.

Delete a contact person

Delete an existing contact person.

DELETE /customers/{customer_id}/contactpersons/{contactperson_id}

Request Example

  
$ curl https://subscriptions.zoho.com/api/v1/customers/{customer_id}/contactpersons/{contactperson_id} -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "X-com-zoho-subscriptions-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The contact person has been deleted." }

List of all contact persons

List of all contact persons of a customer.

GET /customers/{customer_id}/contactpersons

Request Example

  
$ curl https://subscriptions.zoho.com/api/v1/customers/{customer_id}/contactpersons -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "X-com-zoho-subscriptions-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "contact_persons": [ { "contactperson_id": "903000000053362", "first_name": "Mark", "last_name": "Cruizer", "email": "mark.cruzer@bowmanfurniture.com", "mobile": "786663728", "phone": "0417254482" }, {...}, {...} ] }

Cards

A card object shows the credit card information for a particular customer

Example

{ "card_id": "90300000079226", "last_four_digits": 2145, "expiry_month": 9, "expiry_year": 2030, "payment_gateway": "payflow_pro", "first_name": "benjamin", "last_name": "franklin", "street": "12 Harington Bay Street", "city": "Salt Lake City", "state": "CA", "zip": 92612, "country": "U.S.A", "created_time": "2016-06-05T12:30:08-0700", "updated_time": "2016-06-05T02:30:08-0700" }

Attribute

card_id
string
Card ID of the card from which payment is about to made by the customer.
last_four_digits
integer
Last four digits of the customer's card.
expiry_month
integer
Expiry month of the customer's card.
expiry_year
integer
Expiry year of the customer's card.
payment_gateway
string
Payment gateway through which payment needs to be made. Supported payment gateway values test_gateway, payflow_pro, stripe, 2checkout, authorize_net, payments_pro, forte, worldpay, wepay.
first_name
string
Customer's first name in card.
last_name
string
Customer's last name in card.
street
string
The street mentioned in the customer's card address.
city
string
City mentioned in the customer's card address.
state
string
State mentioned in the customer's card address.
zip
string
Zip code mentioned in the customer's card address.
country
string
The country mentioned in the customer's card address.
created_time
string
Time at which the contact person was created.
updated_time
string
Time at which the contact person details were last updated.

Create a new credit card

Create a new credit card.

POST /customers/{customer_id}/cards

Request Example

  
$ curl https://subscriptions.zoho.com/api/v1/customers/{customer_id}/cards -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "X-com-zoho-subscriptions-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8" -d '{ "card_number": 4111111111112145, "cvv_number": 232, "expiry_month": 9, "expiry_year": 2030, "payment_gateway": "payflow_pro", "first_name": "benjamin", "last_name": "franklin", "street": "12 Harington Bay Street", "city": "Salt Lake City", "state": "CA", "zip": 92612, "country": "U.S.A" }

Response Example

  
HTTP/1.1 201 Created Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The credit card has been Created", "card": { "customer_id": "9030000005664", "card_id": "90300000079226", "last_four_digits": 2145, "expiry_month": 9, "expiry_year": 2030, "payment_gateway": "payflow_pro", "first_name": "benjamin", "last_name": "franklin", "street": "12 Harington Bay Street", "city": "Salt Lake City", "state": "CA", "zip": 92612, "country": "U.S.A", "created_time": "2016-06-05T12:30:08-0700", "updated_time": "2016-06-05T02:30:08-0700" } }

ARGUMENTS

card_number
Required
Customer's card number.
card_number
Required
Customer's card number.
cvv_number
Required
CVV number of the customer's card.
expiry_month
Required
Expiry month of the customer's card.
expiry_year
Required
Expiry year of the customer's card.
payment_gateway
Required
Payment gateway through which payment needs to be made. Supported payment gateway values test_gateway, payflow_pro, stripe, 2checkout, authorize_net, payments_pro, forte, worldpay, wepay.
first_name
Optional
Customer's first name in card.
last_name
Optional
Customer's last name in card.
street
Required
The street mentioned in the customer's card address.
city
Required
City mentioned in the customer's card address.
state
Required
State mentioned in the customer's card address.
zip
Required
Zip code mentioned in the customer's card address.
country
Required
The country mentioned in the customer's card address.

Retrieve a credit card information

Details of an existing credit card.

GET /customers/{customer_id}/cards/{card_id}

Request Example

  
$ curl https://subscriptions.zoho.com/api/v1/customers/{customer_id}/cards/{card_id} -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "X-com-zoho-subscriptions-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "card": { "customer_id": "9030000005664", "card_id": "90300000079226", "last_four_digits": 2145, "expiry_month": 9, "expiry_year": 2030, "payment_gateway": "payflow_pro", "first_name": "benjamin", "last_name": "franklin", "street": "12 Harington Bay Street", "city": "Salt Lake City", "state": "CA", "zip": 92612, "country": "U.S.A", "created_time": "2016-06-05T12:30:08-0700", "updated_time": "2016-06-05T02:30:08-0700" } }

Update a credit card

Update the details of an existing credit card.

PUT /customers/{customer_id}/cards/{card_id}

Request Example

  
$ curl https://subscriptions.zoho.com/api/v1/customers/{customer_id}/cards/{card_id} -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "X-com-zoho-subscriptions-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8" -d '{ "card_number": 4111111111112145, "cvv_number": 232, "expiry_month": 9, "expiry_year": 2030, "payment_gateway": "payflow_pro", "first_name": "benjamin", "last_name": "franklin", "street": "12 Harington Bay Street", "city": "Salt Lake City", "state": "CA", "zip": 92612, "country": "U.S.A" }

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The credit card details has been updated.", "card": { "customer_id": "9030000005664", "card_id": "90300000079226", "last_four_digits": 2145, "expiry_month": 9, "expiry_year": 2030, "payment_gateway": "payflow_pro", "first_name": "benjamin", "last_name": "franklin", "street": "12 Harington Bay Street", "city": "Salt Lake City", "state": "CA", "zip": 92612, "country": "U.S.A", "created_time": "2016-06-05T12:30:08-0700", "updated_time": "2016-06-05T02:30:08-0700" } }

ARGUMENTS

card_number
Required
Customer's card number.
cvv_number
Required
CVV number of the customer's card.
expiry_month
Required
Expiry month of the customer's card.
expiry_year
Required
Expiry year of the customer's card.
payment_gateway
Required
Payment gateway through which payment needs to be made. Supported payment gateway values test_gateway, payflow_pro, stripe, 2checkout, authorize_net, payments_pro, forte, worldpay, wepay.
first_name
Optional
Customer's first name in card.
last_name
Optional
Customer's last name in card.
street
Required
The street mentioned in the customer's card address.
city
Required
City mentioned in the customer's card address.
state
Required
State mentioned in the customer's card address.
zip
Required
Zip code mentioned in the customer's card address.
country
Required
The country mentioned in the customer's card address.

Delete a credit card

Delete an existing credit card.

DELETE /customers/{customer_id}/cards/{card_id}

Request Example

  
$ curl https://subscriptions.zoho.com/api/v1/customers/{customer_id}/cards/{card_id} -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "X-com-zoho-subscriptions-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The credit card has been deleted." }

List all Active Credit Cards of a Customer

List of all the Active Credit Cards of a Customer

GET /customers/{customer_id}/cards

Request Example

  
$ curl https://subscriptions.zoho.com/api/v1/customers/{customer_id}/cards -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "X-com-zoho-subscriptions-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "cards": [ { "card_id": "90300000079226", "customer_id": "9030000005664", "status": "active", "last_four_digits": 2145, "expiry_month": 9, "expiry_year": 2030, "payment_gateway": "payflow_pro", "created_time": "2016-06-05T12:30:08-0700", "updated_time": "2016-06-05T02:30:08-0700" }, {...}, {...} ] }

Bank-Accounts

A bank account object shows the cbank account information for a particular customer

Example

{ "account_id": "90300000079126", "customer_id": "9030000005664", "customer_name": "Bowman Furniture", "gateway": "authorize_net", "last_four_digits": 2, "status": "active", "last_modified_time": "2016-06-05T02:30:08-0700", "created_time": "2016-06-05T12:30:08-0700", "created_by_id": "9030000067542", "created_by_name": "Benjamin" }

Attribute

account_id
string
Account ID of the bank account from which payment is about to made by the customer.
customer_id
string
Unique ID associated with the customer.
customer_name
string
Name of the customer, whom the bank account is associated.
gateway
string
Payment gateway through which payment needs to be made. Supported payment gateway values test_gateway, payflow_pro, stripe, 2checkout, authorize_net, payments_pro, forte, worldpay, wepay.
last_four_digits
integer
Last four digits of the customer's bank account.
status
string
Status of the bank account.
last_modified_time
string
Time at which the contact person details were last updated.
created_time
string
Time at which the contact person was created.
created_by_id
string
Unique ID to denote the user who added the bank account.
created_by_name
string
Name of the user who added the bank account.

Retrieve a bank account information

Details of an existing bank account.

GET /customers/{customer_id}/bankaccounts/{account_id}

Request Example

  
$ curl https://subscriptions.zoho.com/api/v1/customers/{customer_id}/bankaccounts/{account_id} -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "X-com-zoho-subscriptions-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "bank_accounts": [ { "account_id": "90300000079126", "customer_id": "9030000005664", "customer_name": "Bowman Furniture", "gateway": "authorize_net", "last_four_digits": 2, "status": "active", "last_modified_time": "2016-06-05T02:30:08-0700", "created_time": "2016-06-05T12:30:08-0700", "created_by_id": "9030000067542", "created_by_name": "Benjamin" }, {...}, {...} ] }

Subscriptions

A subscription enables you to charge customers at specified intervals for a plan of their choice.

Example

{ "subscription_id": "90300000079200", "name": "GatorHost-Basic", "status": "live", "amount": 186, "created_at": "2016-06-11", "activated_at": "2016-06-15", "current_term_starts_at": "2016-06-05", "current_term_ends_at": "2016-06-05", "last_billing_at": "2016-06-05", "next_billing_at": "2016-06-30", "expires_at": "2016-06-05", "interval": 1, "interval_unit": "months", "auto_collect": true, "created_time": "2016-06-11T17:57:13-0700", "updated_time": "2016-06-04T16:44:15-0700", "reference_id": "bowmanfurniture", "salesperson_id": "903000000058001", "salesperson_name": "Franklin", "child_invoice_id": "90300000079210", "currency_code": "USD", "currency_symbol": "$", "end_of_term": true, "product_id": "90300000079065", "product_name": "Bowman Furniture", "plan": { "plan_code": "basic-monthly", "name": "GatorHost-Basic", "quantity": 1, "price": 10, "discount": 20, "total": 50, "setup_fee": 20, "plan_description": "Monthly Basic plan", "tax_id": "903000002345", "trial_days": 0 }, "addons": [ { "addon_code": "Email-basic", "name": "GatorHost-Basic", "addon_description": "Monthly addon.", "quantity": 1, "price": 10, "discount": 20, "total": 50, "tax_id": "903000002345" } ], "coupon": { "coupon_code": "Flat10", "discount_amount": 44 }, "card": { "card_id": "9030000079226", "last_four_digits": 2145, "payment_gateway": "payflow_pro", "expiry_month": 9, "expiry_year": 2030 }, "payment_terms": 1, "payment_terms_label": "Due On Receipt", "can_add_bank_account": true, "customer": { "customer_id": "903000000000099", "display_name": "Bowman Furniture", "salutation": "Mr.", "first_name": "Benjamin", "last_name": "George", "email": "benjamin.george@bowmanfurniture.com", "company_name": "Bowman Furniture", "billing_address": { "attention": "Benjamin George", "street": "Harrington Bay Street", "city": "Salt Lake City", "state": "CA", "country": "U.S.A", "zip": 92612, "fax": 4527389 }, "shipping_address": { "attention": "Benjamin George", "street": "Harrington Bay Street", "city": "Salt Lake City", "state": "CA", "zip": 92612, "country": "U.S.A", "fax": 4527389 }, "payment_terms": 1, "payment_terms_label": "Due On Receipt" }, "custom_fields": [ { "value": 129890, "label": "label", "data_type": "text" } ], "contactpersons": [ { "contactperson_id": "903000000000099" } ], "notes": [ { "note_id": "903000076543", "description": "", "commented_by": "Benjamin", "commented_time": "2016-06-11T17:57:13-0700" } ], "payment_gateways": [ { "payment_gateway": "payflow_pro" } ] }

Attribute

subscription_id
string
Unique ID generated for a subscription.
name
string
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.
product_id
string
Product ID of the product to which the plan is associated with.
product_name
string
Name of the product which the plan belongs to.
object
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
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.
object
The object containing the details of the added coupon. coupon_code and discount_amount applied to the invoice total.
coupon_code
string
The coupon code of the coupon which is to be applied to the subscription.
discount_amount
double
The discount amount included in an invoice on applying a coupon.
object
Customer's card object. This contains payment_gateway, last_four_digits, expiry_month and expiry_year.
card_id
string
Enter the card_id of the card which has to be updated.
last_four_digits
integer
Last four digits of the customer's card.
payment_gateway
string
Payment gateway through which payment needs to be made. Supported payment gateway values test_gateway, payflow_pro, stripe, 2checkout, authorize_net, payments_pro, forte, worldpay, wepay.
expiry_month
integer
Expiry month of the customer's card.
expiry_year
integer
Expiry year of the customer's card.
payment_terms
integer
Payment Due details for the invoices.
payment_terms_label
string
Label for the paymet due details.
can_add_bank_account
boolean
Set to true if Bank account can be added for the customer to perform ACH transactions.
object
Customer object of the customer for whom you want to create a subscription. Each object contains display_name, company_name, first_name, last_name, email, fax, currency_code and billing_address.
customer_id
string
Customer ID of the customer for whom a subscription needs to be created.
display_name
string
This will be name which will be displayed in the interface and invoices.
salutation
string
Salutation of the customer.
first_name
string
First name of the customer.
last_name
string
Last name of the customer.
email
string
Email address of the customer.
company_name
string
Registered name of the company the customer represents.
billing_address
object
Customer's billing address object. It contains attention, street, city, state,zip, country and fax.
attention
string
Attention of the customer's billing address.
street
string
Street of the customer's billing address.
city
string
City of the customer's billing address.
state
string
State of the customer's billing address.
country
string
Country of the customer's billing address.
zip
string
Zip code of the customer's billing address.
fax
string
Fax number for the customer's billing address.
shipping_address
object
Customer's shipping address object. It contains attention, street, city, state,zip, country and fax.
attention
Attention of the customer’s shipping address.
street
Street of the customer’s shipping address.
city
City of the customer’s shipping address.
state
State of the customer’s shipping address.
zip
Zip code of the customer’s shipping address.
country
Country of the customer’s shipping address.
fax
Fax number of the customer’s shipping address.
payment_terms
integer
Payment Due details for the invoices.
payment_terms_label
string
Label for the paymet due details.
custom_fields
list
Additional fields for the invoices.
value
string
Value of the custom field.
label
string
Label of the custom field.
data_type
string
Data type of the custom field.
contactpersons
list
List of contact person objects. Each object contains contactperson_id.
contactperson_id
string
Contact person ID of the customer’s contact person.
list
List of objects containing note_id, description, commented_by and commented_time
note_id
string
Unique ID generated for a note.
commented_by
string
Name of the user who added the comment.
commented_time
string
Time at which the comment was added.
payment_gateways
list
List of payment gateways configured for the customer.
payment_gateway
string
Payment gateway through which payment needs to be made. Supported payment gateway values test_gateway, payflow_pro, stripe, 2checkout, authorize_net, payments_pro, forte, worldpay, wepay.

Create a subscription

Create 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.

POST /subscriptions

Request Example

  
$ curl https://subscriptions.zoho.com/api/v1/subscriptions -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "X-com-zoho-subscriptions-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8" -d '{ "customer": { "display_name": "Bowman Furniture", "salutation": "Mr.", "first_name": "Benjamin", "last_name": "George", "email": "benjamin.george@bowmanfurniture.com", "company_name": "Bowman Furniture", "billing_address": { "attention": "Benjamin George", "street": "Harrington Bay Street", "city": "Salt Lake City", "state": "CA", "country": "U.S.A", "zip": 92612, "fax": 4527389 }, "shipping_address": { "attention": "Benjamin George", "street": "Harrington Bay Street", "city": "Salt Lake City", "state": "CA", "zip": 92612, "country": "U.S.A", "fax": 4527389 }, "payment_terms": 1, "payment_terms_label": "Due On Receipt", "custom_fields": [ { "label": "label", "value": 129890 } ], "place_of_contact": "TN", "gst_no": "33AAAAA0000A1Z5", "gst_treatment": "business_gst", "vat_treatment": "non_eu", "vat_reg_no": 51423456782, "country_code": "DE", "is_taxable": true, "tax_id": "903000002345", "tax_authority_id": "903000006345", "tax_authority_name": "ATO", "tax_exemption_id": "903000006345", "tax_exemption_code": "GST FREE" }, "billing_address": { "attention": "Benjamin George", "street": "Harrington Bay Street", "city": "Salt Lake City", "state": "CA", "country": "U.S.A", "zip": 92612, "fax": 4527389 }, "shipping_address": { "attention": "Benjamin George", "street": "Harrington Bay Street", "city": "Salt Lake City", "state": "CA", "zip": 92612, "country": "U.S.A", "fax": 4527389 }, "payment_terms": 1, "payment_terms_label": "Due On Receipt", "custom_fields": [ { "label": "label", "value": 129890 } ], "contactpersons": [ { "contactperson_id": "903000000000099" } ], "starts_at": "2016-06-05", "exchange_rate": 2, "place_of_supply": "TN", "plan": { "plan_code": "basic-monthly", "plan_description": "Monthly Basic plan", "price": 10, "setup_fee": 20, "setup_fee_tax_id": "9030000123123", "quantity": 1, "tax_id": "903000002345", "tax_exemption_id": "903000006345", "tax_exemption_code": "GST FREE", "setup_fee_tax_exemption_id": "9030000123098", "setup_fee_tax_exemption_code": "GST FREE", "exclude_trial": false, "exclude_setup_fee": false, "billing_cycles": -1, "trial_days": 0 }, "addons": [ { "addon_code": "Email-basic", "addon_description": "Monthly addon.", "price": 10, "quantity": 1, "tax_id": "903000002345", "tax_exemption_id": "903000006345", "tax_exemption_code": "GST FREE" } ], "coupon_code": "Flat10", "auto_collect": true, "reference_id": "bowmanfurniture", "salesperson_name": "Franklin", "payment_gateways": [ { "payment_gateway": "payflow_pro" } ] }

Response Example

  
HTTP/1.1 201 Created Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Subscription has been created successfully.", "subscription": { "subscription_id": "90300000079200", "name": "GatorHost-Basic", "status": "live", "amount": 186, "created_at": "2016-06-11", "activated_at": "2016-06-15", "current_term_starts_at": "2016-06-05", "current_term_ends_at": "2016-06-05", "last_billing_at": "2016-06-05", "next_billing_at": "2016-06-30", "expires_at": "2016-06-05", "interval": 1, "interval_unit": "months", "auto_collect": true, "created_time": "2016-06-11T17:57:13-0700", "updated_time": "2016-06-04T16:44:15-0700", "reference_id": "bowmanfurniture", "place_of_supply": "TN", "salesperson_id": "903000000058001", "salesperson_name": "Franklin", "child_invoice_id": "90300000079210", "currency_code": "USD", "currency_symbol": "$", "end_of_term": true, "product_id": "90300000079065", "product_name": "Bowman Furniture", "plan": { "plan_code": "basic-monthly", "name": "GatorHost-Basic", "quantity": 1, "price": 10, "discount": 20, "total": 50, "setup_fee": 20, "plan_description": "Monthly Basic plan", "tax_id": "903000002345", "trial_days": 0 }, "addons": [ { "addon_code": "Email-basic", "name": "GatorHost-Basic", "addon_description": "Monthly addon.", "quantity": 1, "price": 10, "discount": 20, "total": 50, "tax_id": "903000002345" } ], "coupon": { "coupon_code": "Flat10", "discount_amount": 44 }, "card": { "card_id": "9030000079226", "last_four_digits": 2145, "payment_gateway": "payflow_pro", "expiry_month": 9, "expiry_year": 2030 }, "payment_terms": 1, "payment_terms_label": "Due On Receipt", "can_add_bank_account": true, "customer": { "customer_id": "903000000000099", "display_name": "Bowman Furniture", "salutation": "Mr.", "first_name": "Benjamin", "last_name": "George", "email": "benjamin.george@bowmanfurniture.com", "company_name": "Bowman Furniture", "billing_address": { "attention": "Benjamin George", "street": "Harrington Bay Street", "city": "Salt Lake City", "state": "CA", "country": "U.S.A", "zip": 92612, "fax": 4527389 }, "shipping_address": { "attention": "Benjamin George", "street": "Harrington Bay Street", "city": "Salt Lake City", "state": "CA", "zip": 92612, "country": "U.S.A", "fax": 4527389 }, "payment_terms": 1, "payment_terms_label": "Due On Receipt" }, "custom_fields": [ { "index": 1, "label": "label", "value": 129890, "data_type": "text" } ], "taxes": [ { "tax_id": "903000002345", "tax_name": "GST", "tax_amount": "2.50" } ], "contactpersons": [ { "contactperson_id": "903000000000099" } ], "notes": [ { "note_id": "903000076543", "description": "", "commented_by": "Benjamin", "commented_time": "2016-06-11T17:57:13-0700" } ], "payment_gateways": [ { "payment_gateway": "payflow_pro" } ] } }

ARGUMENTS

Required for creating a subscription for new customer.
Customer object of the customer for whom you want to create a subscription. Each object contains display_name, company_name, first_name, last_name, email, fax, currency_code and billing_address.
display_name
Required
This will be name which will be displayed in the interface and invoices.
salutation
Optional
Salutation of the customer.
first_name
Optional
First name of the customer.
last_name
Optional
Last name of the customer.
email
Required
Email address of the customer.
company_name
Optional
Registered name of the company the customer represents.
billing_address
Optional
Customer's billing address object. It contains attention, street, city, state,zip, country and fax.
attention
Optional
Attention of the customer's billing address.
street
Optional
Street of the customer's billing address.
city
Optional
City of the customer's billing address.
state
Optional
State of the customer's billing address.
country
Optional
Country of the customer's billing address.
zip
Optional
Zip code of the customer's billing address.
fax
Optional
Fax number for the customer's billing address.
shipping_address
Optional
Customer's shipping address object. It contains attention, street, city, state,zip, country and fax.
attention
Optional
Attention of the customer’s shipping address.
street
Optional
Street of the customer’s shipping address.
city
Optional
City of the customer’s shipping address.
state
Optional
State of the customer’s shipping address.
zip
Optional
Zip code of the customer’s shipping address.
country
Optional
Country of the customer’s shipping address.
fax
Optional
Fax number of the customer’s shipping address.
payment_terms
Optional
Payment Due details for the invoices.
payment_terms_label
Optional
Label for the paymet due details.
custom_fields
Optional
Additional fields for the invoices.
label
Required
Label of the custom field.
value
Required
Value of the custom field.
place_of_contact
Applicable for India GST
Optional
Customer's place of contact.
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, overseas
business_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.
billing_address
Optional
Customer's billing address object. It contains attention, street, city, state,zip, country and fax.
attention
Optional
Attention of the customer's billing address.
street
Optional
Street of the customer's billing address.
city
Optional
City of the customer's billing address.
state
Optional
State of the customer's billing address.
country
Optional
Country of the customer's billing address.
zip
Optional
Zip code of the customer's billing address.
fax
Optional
Fax number for the customer's billing address.
shipping_address
Optional
Customer's shipping address object. It contains attention, street, city, state,zip, country and fax.
attention
Optional
Attention of the customer’s shipping address.
street
Optional
Street of the customer’s shipping address.
city
Optional
City of the customer’s shipping address.
state
Optional
State of the customer’s shipping address.
zip
Optional
Zip code of the customer’s shipping address.
country
Optional
Country of the customer’s shipping address.
fax
Optional
Fax number of the customer’s shipping address.
payment_terms
Optional
Payment Due details for the invoices.
payment_terms_label
Optional
Label for the paymet due details.
custom_fields
Optional
Additional fields for the invoices.
label
Required
Label of the custom field.
value
Required
Value of the custom field.
contactpersons
Optional
List of contact person objects. Each object contains contactperson_id.
contactperson_id
Required
Contact person ID of the customer’s contact person.
card_id
Required if auto_collect is true
Enter the card_id of the card which has to be updated.
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.
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.
place_of_supply
Applicable for India GST
Optional
Place of Supply for the customer's subscription.
Required
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.
quantity
Optional
Required quantity of the chosen plan.
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.
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.
Optional
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.
quantity
Optional
Required quantity of the chosen plan.
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.
coupon_code
Optional
The coupon code of the coupon which is to be applied to the subscription.
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.
reference_id
Optional
A string of your choice is required to easily identify and keep track of your subscriptions.
salesperson_name
Optional
Name of the sales person assigned for the subscription.
custom_fields
Optional
Additional fields for the invoices.
label
Required
Label of the custom field.
value
Required
Value of the custom field.
payment_gateways
Optional
List of payment gateways configured for the customer.
payment_gateway
Optional
Payment gateway through which payment needs to be made. Supported payment gateway values test_gateway, payflow_pro, stripe, 2checkout, authorize_net, payments_pro, forte, worldpay, wepay.
salesperson_name
Optional
Name of the sales person assigned for the subscription.

Retrieve a subscription

Details of an existing subscription.

GET /subscriptions/{subscription_id}

Request Example

  
$ curl https://subscriptions.zoho.com/api/v1/subscriptions/{subscription_id} -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "X-com-zoho-subscriptions-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "subscription": { "subscription_id": "90300000079200", "name": "GatorHost-Basic", "status": "live", "amount": 186, "created_at": "2016-06-11", "activated_at": "2016-06-15", "current_term_starts_at": "2016-06-05", "current_term_ends_at": "2016-06-05", "last_billing_at": "2016-06-05", "next_billing_at": "2016-06-30", "expires_at": "2016-06-05", "interval": 1, "interval_unit": "months", "auto_collect": true, "created_time": "2016-06-11T17:57:13-0700", "updated_time": "2016-06-04T16:44:15-0700", "reference_id": "bowmanfurniture", "salesperson_id": "903000000058001", "salesperson_name": "Franklin", "child_invoice_id": "90300000079210", "currency_code": "USD", "currency_symbol": "$", "end_of_term": true, "product_id": "90300000079065", "product_name": "Bowman Furniture", "plan": { "plan_code": "basic-monthly", "name": "GatorHost-Basic", "quantity": 1, "price": 10, "discount": 20, "total": 50, "setup_fee": 20, "plan_description": "Monthly Basic plan", "tax_id": "903000002345", "trial_days": 0 }, "addons": [ { "addon_code": "Email-basic", "name": "GatorHost-Basic", "addon_description": "Monthly addon.", "quantity": 1, "price": 10, "discount": 20, "total": 50, "tax_id": "903000002345" } ], "coupon": { "coupon_code": "Flat10", "discount_amount": 44 }, "card": { "card_id": "9030000079226", "last_four_digits": 2145, "payment_gateway": "payflow_pro", "expiry_month": 9, "expiry_year": 2030 }, "payment_terms": 1, "payment_terms_label": "Due On Receipt", "can_add_bank_account": true, "customer": { "customer_id": "903000000000099", "display_name": "Bowman Furniture", "first_name": "Benjamin", "last_name": "George", "email": "benjamin.george@bowmanfurniture.com", "company_name": "Bowman Furniture", "billing_address": { "attention": "Benjamin George", "street": "Harrington Bay Street", "city": "Salt Lake City", "state": "CA", "country": "U.S.A", "zip": 92612, "fax": 4527389 }, "shipping_address": { "attention": "Benjamin George", "street": "Harrington Bay Street", "city": "Salt Lake City", "state": "CA", "zip": 92612, "country": "U.S.A", "fax": 4527389 }, "payment_terms": 1, "payment_terms_label": "Due On Receipt" }, "custom_fields": [ { "index": 1, "label": "label", "value": 129890, "data_type": "text" } ], "taxes": [ { "tax_id": "903000002345", "tax_name": "GST", "tax_amount": "2.50" } ], "contactpersons": [ { "contactperson_id": "903000000000099" } ], "notes": [ { "note_id": "903000076543", "description": "", "commented_by": "Benjamin", "commented_time": "2016-06-11T17:57:13-0700" } ], "payment_gateways": [ { "payment_gateway": "payflow_pro" } ] } }

Update a subscription

Update details of an existing subscription.

PUT /subscriptions/{subscription_id}

Request Example

  
$ curl https://subscriptions.zoho.com/api/v1/subscriptions/{subscription_id} -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "X-com-zoho-subscriptions-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8" -d '{ "exchange_rate": 2, "plan": { "plan_code": "basic-monthly", "plan_description": "Monthly Basic plan", "price": 10, "setup_fee": 20, "quantity": 1, "tax_id": "903000002345", "tax_exemption_id": "903000006345", "tax_exemption_code": "GST FREE", "setup_fee_tax_exemption_id": "9030000123098", "setup_fee_tax_exemption_code": "GST FREE", "exclude_trial": false, "exclude_setup_fee": false, "billing_cycles": -1, "trial_days": 0 }, "addons": [ { "addon_code": "Email-basic", "addon_description": "Monthly addon.", "price": 10, "quantity": 1, "tax_id": "903000002345", "tax_exemption_id": "903000006345", "tax_exemption_code": "GST FREE" } ], "auto_collect": true, "coupon_code": "Flat10", "reference_id": "bowmanfurniture", "salesperson_name": "Franklin", "end_of_term": true, "contactpersons": [ { "contactperson_id": "903000000000099" } ], "payment_terms": 1, "payment_terms_label": "Due On Receipt", "payment_gateways": [ { "payment_gateway": "payflow_pro" } ] }

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Subscription has been updated successfully.", "subscription": { "subscription_id": "90300000079200", "name": "GatorHost-Basic", "status": "live", "amount": 186, "created_at": "2016-06-11", "activated_at": "2016-06-15", "current_term_starts_at": "2016-06-05", "current_term_ends_at": "2016-06-05", "last_billing_at": "2016-06-05", "next_billing_at": "2016-06-30", "expires_at": "2016-06-05", "interval": 1, "interval_unit": "months", "auto_collect": true, "created_time": "2016-06-11T17:57:13-0700", "updated_time": "2016-06-04T16:44:15-0700", "reference_id": "bowmanfurniture", "salesperson_id": "903000000058001", "salesperson_name": "Franklin", "child_invoice_id": "90300000079210", "currency_code": "USD", "currency_symbol": "$", "end_of_term": true, "product_id": "90300000079065", "product_name": "Bowman Furniture", "plan": { "plan_code": "basic-monthly", "name": "GatorHost-Basic", "quantity": 1, "price": 10, "discount": 20, "total": 50, "setup_fee": 20, "plan_description": "Monthly Basic plan", "tax_id": "903000002345", "trial_days": 0 }, "addons": [ { "addon_code": "Email-basic", "name": "GatorHost-Basic", "addon_description": "Monthly addon.", "quantity": 1, "price": 10, "discount": 20, "total": 50, "tax_id": "903000002345" } ], "coupon": { "coupon_code": "Flat10", "discount_amount": 44 }, "card": { "card_id": "9030000079226", "last_four_digits": 2145, "payment_gateway": "payflow_pro", "expiry_month": 9, "expiry_year": 2030 }, "payment_terms": 1, "payment_terms_label": "Due On Receipt", "can_add_bank_account": true, "customer": { "display_name": "Bowman Furniture", "salutation": "Mr.", "first_name": "Benjamin", "last_name": "George", "email": "benjamin.george@bowmanfurniture.com", "company_name": "Bowman Furniture", "billing_address": { "attention": "Benjamin George", "street": "Harrington Bay Street", "city": "Salt Lake City", "state": "CA", "country": "U.S.A", "zip": 92612, "fax": 4527389 }, "shipping_address": { "attention": "Benjamin George", "street": "Harrington Bay Street", "city": "Salt Lake City", "state": "CA", "zip": 92612, "country": "U.S.A", "fax": 4527389 }, "payment_terms": 1, "payment_terms_label": "Due On Receipt" }, "custom_fields": [ { "index": 1, "label": "label", "value": 129890, "data_type": "text" } ], "taxes": [ { "tax_id": "903000002345", "tax_name": "GST", "tax_amount": "2.50" } ], "contactpersons": [ { "contactperson_id": "903000000000099" } ], "notes": [ { "note_id": "903000076543", "description": "", "commented_by": "Benjamin", "commented_time": "2016-06-11T17:57:13-0700" } ], "payment_gateways": [ { "payment_gateway": "payflow_pro" } ] } }

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.
Required
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.
quantity
Optional
Required quantity of the chosen plan.
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.
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.
Optional
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.
quantity
Optional
Required quantity of the chosen plan.
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.
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_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.
contactpersons
Optional
List of contact person objects. Each object contains contactperson_id.
contactperson_id
Required
Contact person ID of the customer’s contact person.
payment_terms
Optional
Payment Due details for the invoices.
payment_terms_label
Optional
Label for the paymet due details.
payment_gateways
Optional
List of payment gateways configured for the customer.
payment_gateway
Optional
Payment gateway through which payment needs to be made. Supported payment gateway values test_gateway, payflow_pro, stripe, 2checkout, authorize_net, payments_pro, forte, worldpay, wepay.

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.

POST /subscriptions/{subscription_id}/cancel?cancel_at_end=true

Request Example

  
$ curl https://subscriptions.zoho.com/api/v1/subscriptions/{subscription_id}/cancel?cancel_at_end=true -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "X-com-zoho-subscriptions-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Your subscription will be canceled at the end of this term.", "subscription": { "subscription_id": "90300000079200", "name": "GatorHost-Basic", "status": "live", "amount": 186, "created_at": "2016-06-11", "activated_at": "2016-06-15", "current_term_starts_at": "2016-06-05", "current_term_ends_at": "2016-06-05", "last_billing_at": "2016-06-05", "next_billing_at": "2016-06-30", "expires_at": "2016-06-05", "interval": 1, "interval_unit": "months", "auto_collect": true, "created_time": "2016-06-11T17:57:13-0700", "updated_time": "2016-06-04T16:44:15-0700", "reference_id": "bowmanfurniture", "salesperson_id": "903000000058001", "salesperson_name": "Franklin", "child_invoice_id": "90300000079210", "currency_code": "USD", "currency_symbol": "$", "end_of_term": true, "product_id": "90300000079065", "product_name": "Bowman Furniture", "plan": { "plan_code": "basic-monthly", "name": "GatorHost-Basic", "quantity": 1, "price": 10, "discount": 20, "total": 50, "setup_fee": 20, "plan_description": "Monthly Basic plan", "tax_id": "903000002345", "trial_days": 0 }, "addons": [ { "addon_code": "Email-basic", "name": "GatorHost-Basic", "addon_description": "Monthly addon.", "quantity": 1, "price": 10, "discount": 20, "total": 50, "tax_id": "903000002345" } ], "coupon": { "coupon_code": "Flat10", "discount_amount": 44 }, "card": { "card_id": "9030000079226", "last_four_digits": 2145, "payment_gateway": "payflow_pro", "expiry_month": 9, "expiry_year": 2030 }, "payment_terms": 1, "payment_terms_label": "Due On Receipt", "can_add_bank_account": true, "customer": { "customer_id": "903000000000099", "display_name": "Bowman Furniture", "salutation": "Mr.", "first_name": "Benjamin", "last_name": "George", "email": "benjamin.george@bowmanfurniture.com", "company_name": "Bowman Furniture", "billing_address": { "attention": "Benjamin George", "street": "Harrington Bay Street", "city": "Salt Lake City", "state": "CA", "country": "U.S.A", "zip": 92612, "fax": 4527389 }, "shipping_address": { "attention": "Benjamin George", "street": "Harrington Bay Street", "city": "Salt Lake City", "state": "CA", "zip": 92612, "country": "U.S.A", "fax": 4527389 }, "payment_terms": 1, "payment_terms_label": "Due On Receipt" }, "custom_fields": [ { "index": 1, "label": "label", "value": 129890, "data_type": "text" } ], "taxes": [ { "tax_id": "903000002345", "tax_name": "GST", "tax_amount": "2.50" } ], "contactpersons": [ { "contactperson_id": "903000000000099" } ], "notes": [ { "note_id": "903000076543", "description": "", "commented_by": "Benjamin", "commented_time": "2016-06-11T17:57:13-0700" } ], "payment_gateways": [ { "payment_gateway": "payflow_pro" } ] } }

Reactivate subscription

Reactivate a subscription. You can reactivate a subscription only if the `status` of the subscription is non-renewing.

POST /subscriptions/{subscription_id}/reactivate

Request Example

  
$ curl https://subscriptions.zoho.com/api/v1/subscriptions/{subscription_id}/reactivate -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "X-com-zoho-subscriptions-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Subscription has been reactivated successfully.", "subscription": { "subscription_id": "90300000079200", "name": "GatorHost-Basic", "status": "live", "amount": 186, "created_at": "2016-06-11", "activated_at": "2016-06-15", "current_term_starts_at": "2016-06-05", "current_term_ends_at": "2016-06-05", "last_billing_at": "2016-06-05", "next_billing_at": "2016-06-30", "expires_at": "2016-06-05", "interval": 1, "interval_unit": "months", "auto_collect": true, "created_time": "2016-06-11T17:57:13-0700", "updated_time": "2016-06-04T16:44:15-0700", "reference_id": "bowmanfurniture", "salesperson_id": "903000000058001", "salesperson_name": "Franklin", "child_invoice_id": "90300000079210", "currency_code": "USD", "currency_symbol": "$", "end_of_term": true, "product_id": "90300000079065", "product_name": "Bowman Furniture", "plan": { "plan_code": "basic-monthly", "name": "GatorHost-Basic", "quantity": 1, "price": 10, "discount": 20, "total": 50, "setup_fee": 20, "plan_description": "Monthly Basic plan", "billing_cycles": -1, "trial_days": 0 }, "addons": [ { "addon_code": "Email-basic", "name": "GatorHost-Basic", "addon_description": "Monthly addon.", "quantity": 1, "price": 10, "discount": 20, "total": 50 } ], "coupon": { "coupon_code": "Flat10", "discount_amount": 44 }, "card": { "card_id": "9030000079226", "last_four_digits": 2145, "payment_gateway": "payflow_pro", "expiry_month": 9, "expiry_year": 2030 }, "payment_terms": 1, "payment_terms_label": "Due On Receipt", "can_add_bank_account": true, "customer": { "customer_id": "903000000000099", "display_name": "Bowman Furniture", "first_name": "Benjamin", "last_name": "George", "email": "benjamin.george@bowmanfurniture.com", "company_name": "Bowman Furniture", "billing_address": { "attention": "Benjamin George", "street": "Harrington Bay Street", "city": "Salt Lake City", "state": "CA", "country": "U.S.A", "zip": 92612, "fax": 4527389 }, "shipping_address": { "attention": "Benjamin George", "street": "Harrington Bay Street", "city": "Salt Lake City", "state": "CA", "zip": 92612, "country": "U.S.A", "fax": 4527389 }, "payment_terms": 1, "payment_terms_label": "Due On Receipt" }, "custom_fields": [ { "index": 1, "label": "label", "value": 129890, "data_type": "text" } ], "taxes": [ { "tax_id": "903000002345", "tax_name": "GST", "tax_amount": "2.50" } ], "contactpersons": [ { "contactperson_id": "903000000000099" } ], "notes": [ { "note_id": "903000076543", "description": "", "commented_by": "Benjamin", "commented_time": "2016-06-11T17:57:13-0700" } ], "payment_gateways": [ { "payment_gateway": "payflow_pro" } ] } }

Delete a subscription

Delete an existing subscription.

DELETE /subscriptions/{subscription_id}

Request Example

  
$ curl https://subscriptions.zoho.com/api/v1/subscriptions/{subscription_id} -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "X-com-zoho-subscriptions-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The subscription has been deleted." }

View Scheduled Changes

To view the End of Term changes.

GET /subscriptions/{subscription_id}/scheduledchanges

Request Example

  
$ curl https://subscriptions.zoho.com/api/v1/subscriptions/{subscription_id}/scheduledchanges -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "X-com-zoho-subscriptions-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "subscription": { "subscription_id": "90300000079200", "name": "GatorHost-Basic", "status": "live", "amount": 186, "created_at": "2016-06-11", "activated_at": "2016-06-15", "current_term_ends_at": "2016-06-05", "current_term_starts_at": "2016-06-05", "last_billing_at": "2016-06-05", "next_billing_at": "2016-06-30", "expires_at": "2016-06-05", "interval": 1, "interval_unit": "months", "auto_collect": true, "created_time": "2016-06-11T17:57:13-0700", "updated_time": "2016-06-04T16:44:15-0700", "reference_id": "bowmanfurniture", "salesperson_id": "903000000058001", "salesperson_name": "Franklin", "currency_code": "USD", "currency_symbol": "$", "product_id": "90300000079065", "plan": { "plan_code": "basic-monthly", "name": "GatorHost-Basic", "quantity": 1, "price": 10, "discount": 20, "total": 50, "setup_fee": 20, "plan_description": "Monthly Basic plan", "tax_id": "903000002345", "trial_days": 0 }, "addons": [ { "addon_code": "Email-basic", "name": "GatorHost-Basic", "addon_description": "Monthly addon.", "quantity": 1, "price": 10, "discount": 20, "total": 50, "tax_id": "903000002345" } ], "taxes": [ { "tax_id": "903000002345", "tax_name": "GST", "tax_amount": "2.50" } ], "coupon": { "coupon_code": "Flat10", "discount_amount": 44 }, "tax_id": "903000002345" } }

List all subscriptions

List of subscriptions that match the given subscription status. The possible values for SubscriptionStatus are All, ACTIVE, LIVE, FUTURE, TRIAL, PAST_DUE, UNPAID, NON_RENEWING, CANCELLED_FROM_DUNNING, CANCELLED, EXPIRED, TRIAL_EXPIRED, CANCELLED_LAST_MONTH, CANCELLED_THIS_MONTH.

To list the subscriptions of a particular customer append a param customer_id={customer_id}.

To list subscriptions based on Online/Offline, pass the filter_by value as SubscriptionMode.ONLINE or SubscriptionMode.OFFLINE.

GET /subscriptions?filter_by=SubscriptionStatus.ACTIVE

Request Example

  
$ curl https://subscriptions.zoho.com/api/v1/subscriptions?filter_by=SubscriptionStatus.ACTIVE -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "X-com-zoho-subscriptions-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "subscriptions": [ { "customer_id": "903000000000099", "customer_name": "Benjamin", "email": "benjamin.george@bowmanfurniture.com", "plan_name": "Basic Monthly", "subscription_id": "90300000079200", "name": "GatorHost-Basic", "status": "live", "amount": 186, "created_at": "2016-06-11", "activated_at": "2016-06-15", "current_term_ends_at": "2016-06-05", "current_term_starts_at": "2016-06-05", "last_billing_at": "2016-06-05", "next_billing_at": "2016-06-30", "expires_at": "2016-06-05", "interval": 1, "interval_unit": "months", "auto_collect": true, "created_time": "2016-06-11T17:57:13-0700", "updated_time": "2016-06-04T16:44:15-0700", "reference_id": "bowmanfurniture", "salesperson_id": "903000000058001", "salesperson_name": "Franklin", "currency_code": "USD", "currency_symbol": "$" }, {...}, {...} ] }

Subscription Activities

List of all the recent activities associated to a subscription.

GET /subscriptions/{subscription_id}/recentactivities

Request Example

  
$ curl https://subscriptions.zoho.com/api/v1/subscriptions/{subscription_id}/recentactivities -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "X-com-zoho-subscriptions-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "activities": [ { "activity_id": "90300000745213", "description": "Invoice created - INV-000241", "activity_time": "2016-06-11T17:57:13-0700", "commented_by": "Zoho Subscriptions" }, {...}, {...} ] }

Buy one-time addon

Include a one-time addon in the subscription.

POST /subscriptions/{subscription_id}/buyonetimeaddon

Request Example

  
$ curl https://subscriptions.zoho.com/api/v1/subscriptions/{subscription_id}/buyonetimeaddon -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "X-com-zoho-subscriptions-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8" -d '{ "addons": [ { "addon_code": "Email-basic", "quantity": 1, "price": 10, "tax_id": "903000002345", "tax_exemption_id": "903000006345", "tax_exemption_code": "GST FREE", "product_type": "goods" } ], "exchange_rate": 2 }

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "One-time addon has been purchased successfully.", "invoice": { "invoice_id": "9030000079426", "number": "INV-384", "status": "live", "invoice_date": "2016-06-15", "due_date": "2016-06-15", "payment_expected_date": "10-05-2016", "ach_payment_initiated": true, "invoice_items": [ { "item_id": "90300000079434", "name": "GatorHost-Basic", "description": "", "code": "basic-monthly", "price": 10, "quantity": 1, "discount_amount": 44, "item_total": 400 } ], "transaction_type": "invoice", "customer_id": "903000000000099", "customer_name": "Benjamin", "email": "benjamin.george@bowmanfurniture.com", "total": 50, "payment_made": 370, "balance": 0, "coupons": [ { "coupon_code": "Flat10", "coupon_name": "Flat 10", "discount_amount": 44 } ], "credits_applied": 0, "credits": [ { "creditnote_id": "9030000079876", "creditnotes_number": "CN-26", "credited_date": "2016-06-15", "credited_amount": 15 } ], "taxes": [ { "tax_id": "903000002345", "tax_name": "GST", "tax_amount": "2.50" } ], "custom_fields": [ { "index": 1, "label": "label", "value": 129890, "data_type": "text" } ], "salesperson_id": "903000000058001", "salesperson_name": "Franklin", "write_off_amount": 0, "payments": [ { "payment_id": "90300000079467", "payment_mode": "autotransaction", "invoice_payment_id": "9030000079469", "gateway_transaction_id": "9030000056453", "description": "", "date": "2016-06-15", "reference_number": "INV-384", "amount": 186, "exchange_rate": 2 } ], "currency_code": "USD", "currency_symbol": "$", "created_time": "2016-06-11T17:57:13-0700", "updated_time": "2016-06-04T16:44:15-0700", "billing_address": { "attention": "Benjamin George", "street": "Harrington Bay Street", "city": "Salt Lake City", "state": "CA", "country": "U.S.A", "zip": 92612, "fax": 4527389 }, "shipping_address": { "attention": "Benjamin George", "street": "Harrington Bay Street", "city": "Salt Lake City", "state": "CA", "zip": 92612, "country": "U.S.A", "fax": 4527389 }, "comments": [ { "comment_id": "90300000003133", "description": "", "commented_by_id": "90300000002099", "commented_by": "Benjamin", "comment_type": "system", "date": "2016-06-15", "time": "2016-06-11T17:57:13-0700", "operation_type": "add", "transaction_id": "9030000079467", "transaction_type": "invoice" } ] } }

ARGUMENTS

Required
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.
quantity
Optional
Required quantity of the chosen plan.
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.
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.

Associate a coupon

Apply a coupon to a subscription which has been already created.

POST /subscriptions/{subscription_id}/coupons/{coupon_code}

Request Example

  
$ curl https://subscriptions.zoho.com/api/v1/subscriptions/{subscription_id}/coupons/{coupon_code} -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "X-com-zoho-subscriptions-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The coupon has been added to the subscription." }

Remove a coupon

To remove coupon associated with a subscription

DELETE /subscriptions/{subscription_id}/coupons

Request Example

  
$ curl https://subscriptions.zoho.com/api/v1/subscriptions/{subscription_id}/coupons -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "X-com-zoho-subscriptions-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The coupon has been removed from the subscription." }

Update Card

Update the card details of a customer. Once updated, the past card will no longer be charged.

POST /subscriptions/{subscription_id}/card

Request Example

  
$ curl https://subscriptions.zoho.com/api/v1/subscriptions/{subscription_id}/card -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "X-com-zoho-subscriptions-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8" -d '{ "card_id": "9030000079226", "auto_collect": true }

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Card has been updated successfully.", "subscription": { "subscription_id": "90300000079200", "name": "GatorHost-Basic", "status": "live", "amount": 186, "created_at": "2016-06-11", "activated_at": "2016-06-15", "current_term_starts_at": "2016-06-05", "current_term_ends_at": "2016-06-05", "last_billing_at": "2016-06-05", "next_billing_at": "2016-06-30", "expires_at": "2016-06-05", "interval": 1, "interval_unit": "months", "auto_collect": true, "created_time": "2016-06-11T17:57:13-0700", "updated_time": "2016-06-04T16:44:15-0700", "reference_id": "bowmanfurniture", "salesperson_id": "903000000058001", "salesperson_name": "Franklin", "child_invoice_id": "90300000079210", "currency_code": "USD", "currency_symbol": "$", "end_of_term": true, "product_id": "90300000079065", "product_name": "Bowman Furniture", "plan": { "plan_code": "basic-monthly", "name": "GatorHost-Basic", "quantity": 1, "price": 10, "discount": 20, "total": 50, "setup_fee": 20, "plan_description": "Monthly Basic plan", "tax_id": "903000002345", "trial_days": 0 }, "addons": [ { "addon_code": "Email-basic", "name": "GatorHost-Basic", "addon_description": "Monthly addon.", "quantity": 1, "price": 10, "discount": 20, "total": 50, "tax_id": "903000002345" } ], "coupon": { "coupon_code": "Flat10", "discount_amount": 44 }, "card": { "card_id": "9030000079226", "last_four_digits": 2145, "payment_gateway": "payflow_pro", "expiry_month": 9, "expiry_year": 2030 }, "payment_terms": 1, "payment_terms_label": "Due On Receipt", "can_add_bank_account": true, "customer": { "customer_id": "903000000000099", "display_name": "Bowman Furniture", "first_name": "Benjamin", "last_name": "George", "email": "benjamin.george@bowmanfurniture.com", "company_name": "Bowman Furniture", "billing_address": { "attention": "Benjamin George", "street": "Harrington Bay Street", "city": "Salt Lake City", "state": "CA", "country": "U.S.A", "zip": 92612, "fax": 4527389 }, "shipping_address": { "attention": "Benjamin George", "street": "Harrington Bay Street", "city": "Salt Lake City", "state": "CA", "zip": 92612, "country": "U.S.A", "fax": 4527389 }, "payment_terms": 1, "payment_terms_label": "Due On Receipt" }, "custom_fields": [ { "index": 1, "label": "label", "value": 129890, "data_type": "text" } ], "contactpersons": [ { "contactperson_id": "903000000000099" } ], "notes": [ { "note_id": "903000076543", "description": "", "commented_by": "Benjamin", "commented_time": "2016-06-11T17:57:13-0700" } ], "payment_gateways": [ { "payment_gateway": "payflow_pro" } ] } }

ARGUMENTS

card_id
Required
Enter the card_id of the card which has to be updated.
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.

Remove Card

Delete a card associated with the subscription. The subscription will become an offline subscription.

DELETE /subscriptions/{subscription_id}/card

Request Example

  
$ curl https://subscriptions.zoho.com/api/v1/subscriptions/{subscription_id}/card -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "X-com-zoho-subscriptions-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Card has been successfully removed from the subscription." }

Add Charge

Charge a one-time amount for the subscription.

POST /subscriptions/{subscription_id}/charge

Request Example

  
$ curl https://subscriptions.zoho.com/api/v1/subscriptions/{subscription_id}/charge -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "X-com-zoho-subscriptions-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8" -d '{ "amount": 186, "description": "" }

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "One time charge has been added successfully.", "invoice": { "invoice_id": "9030000079426", "number": "INV-384", "status": "live", "invoice_date": "2016-06-15", "due_date": "2016-06-15", "payment_expected_date": "10-05-2016", "ach_payment_initiated": true, "transaction_type": "invoice", "customer_id": "903000000000099", "customer_name": "Benjamin", "email": "benjamin.george@bowmanfurniture.com", "total": 50, "payment_made": 370, "balance": 0, "credits_applied": 0, "write_off_amount": 0, "payments": [ { "payment_id": "90300000079467", "payment_mode": "autotransaction", "invoice_payment_id": "9030000079469", "gateway_transaction_id": "9030000056453", "description": "", "date": "2016-06-15", "reference_number": "INV-384", "amount": 186, "exchange_rate": 2 } ], "currency_code": "USD", "currency_symbol": "$", "created_time": "2016-06-11T17:57:13-0700", "updated_time": "2016-06-04T16:44:15-0700", "billing_address": { "attention": "Benjamin George", "street": "Harrington Bay Street", "city": "Salt Lake City", "state": "CA", "country": "U.S.A", "zip": 92612, "fax": 4527389 }, "comments": [ { "comment_id": "90300000003133", "description": "", "commented_by_id": "90300000002099", "commented_by": "Benjamin", "comment_type": "system", "date": "2016-06-15", "time": "2016-06-11T17:57:13-0700", "operation_type": "add", "transaction_id": "9030000079467", "transaction_type": "invoice" } ] } }

ARGUMENTS

amount
Required
The amount that needs to be charged for the subscription.
description
Optional
Make a note of why the customer was charged so that if can be used for any future reference.

Add contact person

Associate a contact person with the subscription. Only an existing contact person can be associated.

POST /subscriptions/{subscription_id}/contactpersons

Request Example

  
$ curl https://subscriptions.zoho.com/api/v1/subscriptions/{subscription_id}/contactpersons -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "X-com-zoho-subscriptions-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8" -d '{ "contactpersons": [ { "contactperson_id": "903000000000099" } ] }

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The contact person's information has been added.", "subscription": { "subscription_id": "90300000079200", "name": "GatorHost-Basic", "status": "live", "amount": 186, "created_at": "2016-06-11", "activated_at": "2016-06-15", "current_term_starts_at": "2016-06-05", "current_term_ends_at": "2016-06-05", "last_billing_at": "2016-06-05", "next_billing_at": "2016-06-30", "expires_at": "2016-06-05", "interval": 1, "interval_unit": "months", "auto_collect": true, "created_time": "2016-06-11T17:57:13-0700", "updated_time": "2016-06-04T16:44:15-0700", "reference_id": "bowmanfurniture", "salesperson_id": "903000000058001", "salesperson_name": "Franklin", "child_invoice_id": "90300000079210", "currency_code": "USD", "currency_symbol": "$", "end_of_term": true, "product_id": "90300000079065", "product_name": "Bowman Furniture", "plan": { "plan_code": "basic-monthly", "name": "GatorHost-Basic", "quantity": 1, "price": 10, "discount": 20, "total": 50, "setup_fee": 20, "plan_description": "Monthly Basic plan", "tax_id": "903000002345", "trial_days": 0 }, "addons": [ { "addon_code": "Email-basic", "name": "GatorHost-Basic", "addon_description": "Monthly addon.", "quantity": 1, "price": 10, "discount": 20, "total": 50, "tax_id": "903000002345" } ], "coupon": { "coupon_code": "Flat10", "discount_amount": 44 }, "card": { "card_id": "9030000079226", "last_four_digits": 2145, "payment_gateway": "payflow_pro", "expiry_month": 9, "expiry_year": 2030 }, "payment_terms": 1, "payment_terms_label": "Due On Receipt", "can_add_bank_account": true, "customer": { "customer_id": "903000000000099", "display_name": "Bowman Furniture", "first_name": "Benjamin", "last_name": "George", "email": "benjamin.george@bowmanfurniture.com", "company_name": "Bowman Furniture", "billing_address": { "attention": "Benjamin George", "street": "Harrington Bay Street", "city": "Salt Lake City", "state": "CA", "country": "U.S.A", "zip": 92612, "fax": 4527389 }, "shipping_address": { "attention": "Benjamin George", "street": "Harrington Bay Street", "city": "Salt Lake City", "state": "CA", "zip": 92612, "country": "U.S.A", "fax": 4527389 }, "payment_terms": 1, "payment_terms_label": "Due On Receipt" }, "custom_fields": [ { "index": 1, "label": "label", "value": 129890, "data_type": "text" } ], "taxes": [ { "tax_id": "903000002345", "tax_name": "GST", "tax_amount": "2.50" } ], "contactpersons": [ { "contactperson_id": "903000000000099" } ], "notes": [ { "note_id": "903000076543", "description": "", "commented_by": "Benjamin", "commented_time": "2016-06-11T17:57:13-0700" } ], "payment_gateways": [ { "payment_gateway": "payflow_pro" } ] } }

ARGUMENTS

contactpersons
Required
List of contact person objects. Each object contains contactperson_id.
contactperson_id
Required
Contact person ID of the customer’s contact person.

Postpone renewal

A subscription renewal date (billing date) can be postponed thereby extending the subscription term. Also, subscription renewal can only be postponed and not preponed.

POST /subscriptions/{subscription_id}/postpone

Request Example

  
$ curl https://subscriptions.zoho.com/api/v1/subscriptions/{subscription_id}/postpone -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "X-com-zoho-subscriptions-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8" -d '{ "renewal_at": "2016-06-24" }

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Billing date of the subscription has been changed.", "subscription": { "subscription_id": "90300000079200", "name": "GatorHost-Basic", "status": "live", "amount": 186, "created_at": "2016-06-11", "activated_at": "2016-06-15", "current_term_starts_at": "2016-06-05", "current_term_ends_at": "2016-06-05", "last_billing_at": "2016-06-05", "next_billing_at": "2016-06-30", "expires_at": "2016-06-05", "interval": 1, "interval_unit": "months", "auto_collect": true, "created_time": "2016-06-11T17:57:13-0700", "updated_time": "2016-06-04T16:44:15-0700", "reference_id": "bowmanfurniture", "salesperson_id": "903000000058001", "salesperson_name": "Franklin", "child_invoice_id": "90300000079210", "currency_code": "USD", "currency_symbol": "$", "end_of_term": true, "product_id": "90300000079065", "product_name": "Bowman Furniture", "plan": { "plan_code": "basic-monthly", "name": "GatorHost-Basic", "quantity": 1, "price": 10, "discount": 20, "total": 50, "setup_fee": 20, "plan_description": "Monthly Basic plan", "tax_id": "903000002345", "trial_days": 0 }, "addons": [ { "addon_code": "Email-basic", "name": "GatorHost-Basic", "addon_description": "Monthly addon.", "quantity": 1, "price": 10, "discount": 20, "total": 50, "tax_id": "903000002345" } ], "coupon": { "coupon_code": "Flat10", "discount_amount": 44 }, "card": { "card_id": "9030000079226", "last_four_digits": 2145, "payment_gateway": "payflow_pro", "expiry_month": 9, "expiry_year": 2030 }, "payment_terms": 1, "payment_terms_label": "Due On Receipt", "can_add_bank_account": true, "customer": { "customer_id": "903000000000099", "display_name": "Bowman Furniture", "first_name": "Benjamin", "last_name": "George", "email": "benjamin.george@bowmanfurniture.com", "company_name": "Bowman Furniture", "billing_address": { "attention": "Benjamin George", "street": "Harrington Bay Street", "city": "Salt Lake City", "state": "CA", "country": "U.S.A", "zip": 92612, "fax": 4527389 }, "shipping_address": { "attention": "Benjamin George", "street": "Harrington Bay Street", "city": "Salt Lake City", "state": "CA", "zip": 92612, "country": "U.S.A", "fax": 4527389 }, "payment_terms": 1, "payment_terms_label": "Due On Receipt" }, "custom_fields": [ { "index": 1, "label": "label", "value": 129890, "data_type": "text" } ], "taxes": [ { "tax_id": "903000002345", "tax_name": "GST", "tax_amount": "2.50" } ], "contactpersons": [ { "contactperson_id": "903000000000099" } ], "notes": [ { "note_id": "903000076543", "description": "", "commented_by": "Benjamin", "commented_time": "2016-06-11T17:57:13-0700" } ], "payment_gateways": [ { "payment_gateway": "payflow_pro" } ] } }

ARGUMENTS

renewal_at
Required
Enter the future date to which the subscription renewal has to be postponed.

Add/Edit description for a plan in line items list

Add/Edit description to a particular plan in the line items list

POST /subscriptions/{subscription_id}/lineitems/{plan_code}

Request Example

  
$ curl https://subscriptions.zoho.com/api/v1/subscriptions/{subscription_id}/lineitems/{plan_code} -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "X-com-zoho-subscriptions-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8" -d '{ "description": "" }

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Item description has been updated successfully." }

ARGUMENTS

description
Required
Make a note of why the customer was charged so that if can be used for any future reference.

Add/Edit description for a addon in line items list

Add/Edit description to a particular addon in the line items list

POST /subscriptions/{subscription_id}/lineitems/{addon_code}

Request Example

  
$ curl https://subscriptions.zoho.com/api/v1/subscriptions/{subscription_id}/lineitems/{addon_code} -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "X-com-zoho-subscriptions-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8" -d '{ "description": "" }

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Item description has been updated successfully." }

ARGUMENTS

description
Required
Make a note of why the customer was charged so that if can be used for any future reference.

Change to Online/Offline mode

Change the status of a particular subscription to Online/Offline mode. If auto_collect is false, the subscription is in Offline mode. If auto_collect is true, the subscription is in Online mode.

POST /subscriptions/{subscription_id}/autocollect

Request Example

  
$ curl https://subscriptions.zoho.com/api/v1/subscriptions/{subscription_id}/autocollect -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "X-com-zoho-subscriptions-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8" -d '{ "auto_collect": true }

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Auto charge Status has been changed successfully.", "subscription": { "subscription_id": "90300000079200", "name": "GatorHost-Basic", "status": "live", "amount": 186, "created_at": "2016-06-11", "activated_at": "2016-06-15", "current_term_starts_at": "2016-06-05", "current_term_ends_at": "2016-06-05", "last_billing_at": "2016-06-05", "next_billing_at": "2016-06-30", "expires_at": "2016-06-05", "interval": 1, "interval_unit": "months", "auto_collect": true, "created_time": "2016-06-11T17:57:13-0700", "updated_time": "2016-06-04T16:44:15-0700", "reference_id": "bowmanfurniture", "salesperson_id": "903000000058001", "salesperson_name": "Franklin", "child_invoice_id": "90300000079210", "currency_code": "USD", "currency_symbol": "$", "end_of_term": true, "product_id": "90300000079065", "product_name": "Bowman Furniture", "plan": { "plan_code": "basic-monthly", "name": "GatorHost-Basic", "quantity": 1, "price": 10, "discount": 20, "total": 50, "setup_fee": 20, "plan_description": "Monthly Basic plan", "tax_id": "903000002345", "trial_days": 0 }, "addons": [ { "addon_code": "Email-basic", "name": "GatorHost-Basic", "addon_description": "Monthly addon.", "quantity": 1, "price": 10, "discount": 20, "total": 50, "tax_id": "903000002345" } ], "coupon": { "coupon_code": "Flat10", "discount_amount": 44 }, "card": { "card_id": "9030000079226", "last_four_digits": 2145, "payment_gateway": "payflow_pro", "expiry_month": 9, "expiry_year": 2030 }, "payment_terms": 1, "payment_terms_label": "Due On Receipt", "can_add_bank_account": true, "customer": { "customer_id": "903000000000099", "display_name": "Bowman Furniture", "first_name": "Benjamin", "last_name": "George", "email": "benjamin.george@bowmanfurniture.com", "company_name": "Bowman Furniture", "billing_address": { "attention": "Benjamin George", "street": "Harrington Bay Street", "city": "Salt Lake City", "state": "CA", "country": "U.S.A", "zip": 92612, "fax": 4527389 }, "shipping_address": { "attention": "Benjamin George", "street": "Harrington Bay Street", "city": "Salt Lake City", "state": "CA", "zip": 92612, "country": "U.S.A", "fax": 4527389 }, "payment_terms": 1, "payment_terms_label": "Due On Receipt" }, "custom_fields": [ { "index": 1, "label": "label", "value": 129890, "data_type": "text" } ], "taxes": [ { "tax_id": "903000002345", "tax_name": "GST", "tax_amount": "2.50" } ], "contactpersons": [ { "contactperson_id": "903000000000099" } ], "notes": [ { "note_id": "903000076543", "description": "", "commented_by": "Benjamin", "commented_time": "2016-06-11T17:57:13-0700" } ], "payment_gateways": [ { "payment_gateway": "payflow_pro" } ] } }

ARGUMENTS

auto_collect
Required
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.

Update Reference

Update reference id to easily identify and keep track of your subscription

POST /subscriptions/{subscription_id}/reference

Request Example

  
$ curl https://subscriptions.zoho.com/api/v1/subscriptions/{subscription_id}/reference -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "X-com-zoho-subscriptions-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8" -d '{ "reference_id": "9030000034432" }

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Subscription has been updated successfully.", "subscription": { "subscription_id": "90300000079200", "name": "GatorHost-Basic", "status": "live", "amount": 186, "created_at": "2016-06-11", "activated_at": "2016-06-15", "current_term_starts_at": "2016-06-05", "current_term_ends_at": "2016-06-05", "last_billing_at": "2016-06-05", "next_billing_at": "2016-06-30", "expires_at": "2016-06-05", "interval": 1, "interval_unit": "months", "auto_collect": true, "created_time": "2016-06-11T17:57:13-0700", "updated_time": "2016-06-04T16:44:15-0700", "reference_id": "bowmanfurniture", "salesperson_id": "903000000058001", "salesperson_name": "Franklin", "child_invoice_id": "90300000079210", "currency_code": "USD", "currency_symbol": "$", "end_of_term": true, "product_id": "90300000079065", "product_name": "Bowman Furniture", "plan": { "plan_code": "basic-monthly", "name": "GatorHost-Basic", "quantity": 1, "price": 10, "discount": 20, "total": 50, "setup_fee": 20, "plan_description": "Monthly Basic plan", "tax_id": "903000002345", "trial_days": 0 }, "addons": [ { "addon_code": "Email-basic", "name": "GatorHost-Basic", "addon_description": "Monthly addon.", "quantity": 1, "price": 10, "discount": 20, "total": 50, "tax_id": "903000002345" } ], "coupon": { "coupon_code": "Flat10", "discount_amount": 44 }, "card": { "card_id": "9030000079226", "last_four_digits": 2145, "payment_gateway": "payflow_pro", "expiry_month": 9, "expiry_year": 2030 }, "payment_terms": 1, "payment_terms_label": "Due On Receipt", "can_add_bank_account": true, "customer": { "customer_id": "903000000000099", "display_name": "Bowman Furniture", "first_name": "Benjamin", "last_name": "George", "email": "benjamin.george@bowmanfurniture.com", "company_name": "Bowman Furniture", "billing_address": { "attention": "Benjamin George", "street": "Harrington Bay Street", "city": "Salt Lake City", "state": "CA", "country": "U.S.A", "zip": 92612, "fax": 4527389 }, "shipping_address": { "attention": "Benjamin George", "street": "Harrington Bay Street", "city": "Salt Lake City", "state": "CA", "zip": 92612, "country": "U.S.A", "fax": 4527389 }, "payment_terms": 1, "payment_terms_label": "Due On Receipt" }, "custom_fields": [ { "index": 1, "label": "label", "value": 129890, "data_type": "text" } ], "taxes": [ { "tax_id": "903000002345", "tax_name": "GST", "tax_amount": "2.50" } ], "contactpersons": [ { "contactperson_id": "903000000000099" } ], "notes": [ { "note_id": "903000076543", "description": "", "commented_by": "Benjamin", "commented_time": "2016-06-11T17:57:13-0700" } ], "payment_gateways": [ { "payment_gateway": "payflow_pro" } ] } }

ARGUMENTS

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

Update Sales Person

Update sales person associated with a particular subscription

POST /subscriptions/{subscription_id}/salesperson

Request Example

  
$ curl https://subscriptions.zoho.com/api/v1/subscriptions/{subscription_id}/salesperson -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "X-com-zoho-subscriptions-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8" -d '{ "salesperson_name": "Franklin" }

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Subscription has been updated successfully.", "subscription": { "subscription_id": "90300000079200", "name": "GatorHost-Basic", "status": "live", "amount": 186, "created_at": "2016-06-11", "activated_at": "2016-06-15", "current_term_starts_at": "2016-06-05", "current_term_ends_at": "2016-06-05", "last_billing_at": "2016-06-05", "next_billing_at": "2016-06-30", "expires_at": "2016-06-05", "interval": 1, "interval_unit": "months", "auto_collect": true, "created_time": "2016-06-11T17:57:13-0700", "updated_time": "2016-06-04T16:44:15-0700", "reference_id": "bowmanfurniture", "salesperson_id": "903000000058001", "salesperson_name": "Franklin", "child_invoice_id": "90300000079210", "currency_code": "USD", "currency_symbol": "$", "end_of_term": true, "product_id": "90300000079065", "product_name": "Bowman Furniture", "plan": { "plan_code": "basic-monthly", "name": "GatorHost-Basic", "quantity": 1, "price": 10, "discount": 20, "total": 50, "setup_fee": 20, "plan_description": "Monthly Basic plan", "tax_id": "903000002345", "trial_days": 0 }, "addons": [ { "addon_code": "Email-basic", "name": "GatorHost-Basic", "addon_description": "Monthly addon.", "quantity": 1, "price": 10, "discount": 20, "total": 50, "tax_id": "903000002345" } ], "coupon": { "coupon_code": "Flat10", "discount_amount": 44 }, "card": { "card_id": "9030000079226", "last_four_digits": 2145, "payment_gateway": "payflow_pro", "expiry_month": 9, "expiry_year": 2030 }, "payment_terms": 1, "payment_terms_label": "Due On Receipt", "can_add_bank_account": true, "customer": { "customer_id": "903000000000099", "display_name": "Bowman Furniture", "first_name": "Benjamin", "last_name": "George", "email": "benjamin.george@bowmanfurniture.com", "company_name": "Bowman Furniture", "billing_address": { "attention": "Benjamin George", "street": "Harrington Bay Street", "city": "Salt Lake City", "state": "CA", "country": "U.S.A", "zip": 92612, "fax": 4527389 }, "shipping_address": { "attention": "Benjamin George", "street": "Harrington Bay Street", "city": "Salt Lake City", "state": "CA", "zip": 92612, "country": "U.S.A", "fax": 4527389 }, "payment_terms": 1, "payment_terms_label": "Due On Receipt" }, "custom_fields": [ { "index": 1, "label": "label", "value": 129890, "data_type": "text" } ], "taxes": [ { "tax_id": "903000002345", "tax_name": "GST", "tax_amount": "2.50" } ], "contactpersons": [ { "contactperson_id": "903000000000099" } ], "notes": [ { "note_id": "903000076543", "description": "", "commented_by": "Benjamin", "commented_time": "2016-06-11T17:57:13-0700" } ], "payment_gateways": [ { "payment_gateway": "payflow_pro" } ] } }

ARGUMENTS

salesperson_name
Required
Name of the sales person assigned for the subscription.

Update Custom Fields

Update the custom fields associated with a particular subscription

POST /subscriptions/{subscription_id}/customfields

Request Example

  
$ curl https://subscriptions.zoho.com/api/v1/subscriptions/{subscription_id}/customfields -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "X-com-zoho-subscriptions-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8" -d '{ "custom_fields": [ { "label": "label", "value": 129890 } ] }

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Custom Fields Updated Successfully.", "data": { "index": 1, "value": 129890, "label": "label", "data_type": "text", "customfield_id": "9030000089798" } }

ARGUMENTS

custom_fields
Required
Additional fields for the invoices.
label
Required
Label of the custom field.
value
Required
Value of the custom field.

Add a note

Notes related to the subscription can be added by the user at anytime.

POST /subscriptions/{subscription_id}/notes

Request Example

  
$ curl https://subscriptions.zoho.com/api/v1/subscriptions/{subscription_id}/notes -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "X-com-zoho-subscriptions-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8" -d '{}

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Notes added.", "note": { "notes": [ { "note_id": "903000076543", "description": "", "commented_by": "Benjamin", "commented_time": "2016-06-11T17:57:13-0700" } ] } }

ARGUMENTS

description
Optional
Small description about the note.

Delete a note

Delete a specific note.

DELETE /subscriptions/{subscription_id}/notes/{note_id}

Request Example

  
$ curl https://subscriptions.zoho.com/api/v1/subscriptions/{subscription_id}/notes/{note_id} -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "X-com-zoho-subscriptions-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The note has been deleted.", "note": {...} }

Invoices

Invoices describe how much a customer owes for his subscription. Invoices are created for recurring charges, one time charges including any prorated adjustments.

Example

{ "invoice_id": "903000000079426", "number": "INV-384", "status": "paid", "invoice_date": "2016-06-05", "due_date": "2016-06-05", "payment_expected_date": "10-05-2013", "transaction_type": "renewal", "customer_id": "903000000000099", "customer_name": "Bowman Furniture", "email": "benjamin.george@bowmanfurniture.com", "invoice_items": [ { "item_id": "7000000079434", "name": "Basic", "description": "Payment has been made for the invoice INV-384", "code": "basic-monthly", "price": 50, "quantity": 1, "discount_amount": 80, "item_total": 400, "tax_id": "903002205046032", "product_type": "goods", "hsn_or_sac": "74191010", "tax_exemption_id": "903002205042099", "tax_exemption_code": "NGO" } ], "coupons": [ { "coupon_code": "THANKSGIVING20", "coupon_name": "Flat 10", "discount_amount": 80 } ], "total": 370, "payment_made": 370, "balance": 0, "credits_applied": 0, "write_off_amount": 0, "payments": [ { "payment_id": "90300000079467", "payment_mode": "autotransaction", "invoice_payment_id": "90300000079469", "gateway_transaction_id": "B10E6E0F31BD", "description": "Payment has been made for the invoice INV-384", "date": "2016-06-05", "reference_number": "INV-384", "amount": 370, "bank_charges": 10, "exchange_rate": 1 } ], "currency_code": "USD", "currency_symbol": "$", "created_time": "2016-06-05T02:15:15-0700", "updated_time": "2016-06-05T02:15:15-0700", "invoice_url": "", "billing_address": { "city": "Salt Lake City", "state": "CA", "zip": 92612, "country": "U.S.A", "fax": 4527389 }, "shipping_address": {}, "comments": [ { "comment_id": "9030000003133", "description": "Payment has been made for the invoice INV-384", "commented_by_id": "90300000002099", "commented_by": "Zoho Subscripion", "comment_type": "system", "date": "2016-06-05", "time": "2:50 AM", "operation_type": "Added", "transaction_id": "903000001223", "transaction_type": "renewal" } ] }

Attribute

invoice_id
string
Unique ID generated for an invoice.
number
string
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.
payment_expected_date
string
A date to specify the expected payment date.
transaction_type
string
Type of the transaction made.
customer_id
array
Customer ID of the customer to whom the invoice is raised.
customer_name
string
Name of the customer to whom the invoice is raised.
email
string
Email address of the customer.
invoice_items
list
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.
item_id
string
The ID of the item included in the invoice.
name
string
Name of the item included in the invoice.
code
string
Item code of the item included in the invoice.
price
string
Price of the item included in the invoice.
quantity
integer
Quantity of the item included in the invoice.
discount_amount
double
The discount amount included in an invoice on applying a coupon.
item_total
integer
Cost of an item included in the invoice. This would be the product of quantity of the item included and the price of that item.
tax_id
string
Tax ID to which you would like to associate with this plan.
product_type
Applicable for VAT/India GST
string
Product type for UK Edition.
hsn_or_sac
Applicable for India GST
string
HSN or SAC code for Goods/Services
tax_exemption_id
string
Unique Tax Exemption ID if you dont want to associate a tax to the plan.
tax_exemption_code
string
Unique code to denote the tax exemption.
list
The array of objects which contains the details of the added coupon. coupon_code and discount_amount are applied to the invoice total.
coupon_code
string
The coupon code of the coupon applied to the invoice.
coupon_name
string
Name of the coupon applied to the subscription.
discount_amount
double
The discount amount included in an invoice on applying a coupon.
total
double
Total amount to be paid for the invoice. This would be the sum of individual costs of all items involved in the invoice. Total is determined only after customer credits (if any) are applied.
payment_made
double
Payments can be made in multiple instalments. payment_made refers to the amount paid for the invoice in the respective instalment.
balance
double
The unpaid amount of an invoice.
credits_applied
double
Credits applied for the invoice.
write_off_amount
double
The unpaid amount of an invoice that is written off.
list
List of payment objects. Each object will contain payment_id, payment_mode, invoice_payment_id, gateway_transaction_id, description, date, reference_number, amount and bank_charges.
payment_id
string
The payment ID of the payment made for the invoice.
payment_mode
string
The mode in which payment is made for the invoice. This can be check, cash, creditcard, banktransfer, bankremittance, autotransaction or others.
invoice_payment_id
string
Unique ID generated for an instalment of payment made for a particular invoice.
gateway_transaction_id
string
Gateway transaction ID provided for the payment made to the invoice. This is applicable only if payment_mode is autotransaction.
date
string
Date on which the invoice is paid.
reference_number
string
Reference number of the invoice for which payment is made.
amount
double
Amount paid for the invoice.
bank_charges
double
Denotes any additional bank charges.
exchange_rate
double
Exchange-Rate for the currency.
currency_code
string
The customer's currency code.
currency_symbol
string
The customer's currency symbol.
created_time
string
Time when the invoice was created.
updated_time
string
Time when the invoice details were last updated.
invoice_url
string
Url which corresponds to the invoice.
billing_address
object
Customer's billing address object. It contains street, city, state,zip and country.
city
string
Name of the city of the customer's billing address.
state
string
Name of the state of the customer's billing address.
zip
string
Zip code of the customer's billing address.
country
string
Name of the country of the customer's billing address.
fax
string
Customer's fax number.
shipping_address
object
Customer's shipping address object. It contains street, city, state,zip and country.
list
Lists the comments added by the system or by user.
comment_id
string
Unique Id to denote the comment fro the particular invoice.
commented_by_id
string
Unique Id to denote who has commented.
commented_by
string
It denotes the name of the user who has commented or the system.
comment_type
string
It denotes whether user comment or system comment.
date
string
Date on which the invoice is paid.
time
string
Denotes the time at which the comment was created.
operation_type
string
It denotes the type of operation performed on invoice.
transaction_id
string
Unique which denotes the type of transaction.
transaction_type
string
Type of the transaction made.

Retrieve an invoice

Details of an existing invoice.

GET /invoices/{invoice_id}

Request Example

  
$ curl https://subscriptions.zoho.com/api/v1/invoices/{invoice_id} -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "X-com-zoho-subscriptions-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "invoice": { "invoice_id": "903000000079426", "number": "INV-384", "status": "paid", "invoice_date": "2016-06-05", "due_date": "2016-06-05", "payment_expected_date": "10-05-2013", "ach_payment_initiated": true, "transaction_type": "renewal", "customer_id": "903000000000099", "customer_name": "Bowman Furniture", "email": "benjamin.george@bowmanfurniture.com", "invoice_items": [ { "item_id": "7000000079434", "name": "Basic", "description": "Payment has been made for the invoice INV-384", "code": "basic-monthly", "price": 50, "quantity": 1, "discount_amount": 80, "item_total": 400, "tax_id": "903002205046032", "tax_exemption_id": "903002205042099", "tax_exemption_code": "NGO" } ], "coupons": [ { "coupon_code": "THANKSGIVING20", "coupon_name": "Flat 10", "discount_amount": 80 } ], "credits": [ { "creditnote_id": "9030000079876", "creditnotes_number": "CN-26", "credited_date": "2016-06-15", "credited_amount": 15 } ], "total": 370, "payment_made": 370, "balance": 0, "credits_applied": 0, "write_off_amount": 0, "payments": [ { "payment_id": "90300000079467", "payment_mode": "autotransaction", "invoice_payment_id": "90300000079469", "amount_refunded": 50, "gateway_transaction_id": "B10E6E0F31BD", "description": "Payment has been made for the invoice INV-384", "date": "2016-06-05", "reference_number": "INV-384", "amount": 370, "bank_charges": 10, "exchange_rate": 1 } ], "currency_code": "USD", "currency_symbol": "$", "created_time": "2016-06-05T02:15:15-0700", "updated_time": "2016-06-05T02:15:15-0700", "salesperson_id": "90300023000043", "salesperson_name": "Bowman", "invoice_url": "", "billing_address": { "city": "Salt Lake City", "state": "CA", "zip": 92612, "country": "U.S.A", "fax": 4527389 }, "shipping_address": {...}, "comments": [ { "comment_id": "9030000003133", "description": "Payment has been made for the invoice INV-384", "commented_by_id": "90300000002099", "commented_by": "Zoho Subscripion", "comment_type": "system", "date": "2016-06-05", "time": "2:50 AM", "operation_type": "Added", "transaction_id": "903000001223", "transaction_type": "renewal" } ], "custom_fields": [ { "index": 1, "label": "label", "value": 129890, "data_type": "text" } ] } }

List all invoices

List of all invoices. Invoices of particular status can be filtered by passing a param filter_by. Allowed values are Status.(All, Sent, Draft, OverDue, Paid, PartiallyPaid, Void, Unpaid).

To list invoices for a particular subscription or customer append a param as subscription_id={subscription_id} or customer_id={customer_id}.

GET /invoices?filter_by=Status.All

Request Example

  
$ curl https://subscriptions.zoho.com/api/v1/invoices?filter_by=Status.All -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "X-com-zoho-subscriptions-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "invoices": [ { "invoice_id": "903000000079426", "number": "INV-384", "status": "paid", "invoice_date": "2016-06-05", "due_date": "2016-06-05", "customer_id": "903000000000099", "customer_name": "Bowman Furniture", "email": "benjamin.george@bowmanfurniture.com", "balance": 0, "total": 370, "currency_code": "USD", "currency_symbol": "$", "created_time": "2016-06-05T02:15:15-0700", "updated_time": "2016-06-05T02:15:15-0700" }, {...}, {...} ] }

Collect charge via credit card

Charge a customer for an invoice using existing card.

POST /invoices/{invoice_id}/collect

Request Example

  
$ curl https://subscriptions.zoho.com/api/v1/invoices/{invoice_id}/collect -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "X-com-zoho-subscriptions-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8" -d '{ "card_id": "90300000079226" }

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The customer payment has been recorded.", "payment": { "payment_id": "90300000079467", "payment_mode": "autotransaction", "amount": 370, "amount_refunded": 50, "bank_charges": 10, "date": "2016-06-05", "status": "paid", "reference_number": "INV-384", "description": "Payment has been made for the invoice INV-384", "customer_id": "903000000000099", "customer_name": "Bowman Furniture", "email": "benjamin.george@bowmanfurniture.com", "autotransaction": { "autotransaction_id": "9030000079465", "payment_gateway": "payflow_pro", "gateway_transaction_id": "B10E6E0F31BD", "gateway_error_message": "Gateway error message for a failed transaction.", "card_id": "90300000079226", "last_four_digits": 1111, "expiry_month": 9, "expiry_year": 2030 }, "invoices": [ { "invoice_id": "903000000079426", "invoice_number": "INV-384", "date": "2016-06-05", "invoice_amount": 450, "amount_applied": 450, "balance_amount": 0 } ], "currency_code": "USD", "currency_symbol": "$", "custom_fields": [ { "index": 1, "value": 129890, "label": "label", "data_type": "text" } ], "created_time": "2016-06-05T02:15:15-0700", "updated_time": "2016-06-05T02:15:15-0700" } }

ARGUMENTS

card_id
Required
Card ID of the card associated with the transaction.

Collect charge via bank account

Charge a customer for an invoice using existing bank account.

POST /invoices/{invoice_id}/collect

Request Example

  
$ curl https://subscriptions.zoho.com/api/v1/invoices/{invoice_id}/collect -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "X-com-zoho-subscriptions-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8" -d '{ "account_id": "9030000000000361" }

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The customer payment has been recorded.", "payment": { "payment_id": "90300000079467", "payment_mode": "autotransaction", "amount": 370, "amount_refunded": 50, "bank_charges": 10, "date": "2016-06-05", "status": "paid", "reference_number": "INV-384", "due_date": "2016-06-05", "amount_due": 10, "description": "Payment has been made for the invoice INV-384", "customer_id": "903000000000099", "customer_name": "Bowman Furniture", "email": "benjamin.george@bowmanfurniture.com", "autotransaction": { "autotransaction_id": "9030000079465", "payment_gateway": "payflow_pro", "gateway_transaction_id": "B10E6E0F31BD", "gateway_error_message": "Gateway error message for a failed transaction.", "account_id": "9030000000000361" }, "invoices": [ { "invoice_id": "903000000079426", "invoice_number": "INV-384", "date": "2016-06-05", "invoice_amount": 450, "amount_applied": 450, "balance_amount": 0 } ], "currency_code": "USD", "currency_symbol": "$", "custom_fields": [ { "index": 1, "value": 129890, "label": "label", "data_type": "text" } ], "created_time": "2016-06-05T02:15:15-0700", "updated_time": "2016-06-05T02:15:15-0700" } }

ARGUMENTS

account_id
Required
Unique ID of the bank account.

Convert to void

Making an invoice void.

POST /invoices/{invoice_id}/void

Request Example

  
$ curl https://subscriptions.zoho.com/api/v1/invoices/{invoice_id}/void -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "X-com-zoho-subscriptions-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Invoice has been marked as void." }

Convert to open

Change the status of the invoice to open.

POST /invoices/{invoice_id}/converttoopen

Request Example

  
$ curl https://subscriptions.zoho.com/api/v1/invoices/{invoice_id}/converttoopen -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "X-com-zoho-subscriptions-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Status of the invoice has been changed to open." }

Email an invoice

Email an invoice.

POST /invoices/{invoice_id}/email

Request Example

  
$ curl https://subscriptions.zoho.com/api/v1/invoices/{invoice_id}/email -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "X-com-zoho-subscriptions-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8" -d '{ "to_mail_ids": [ "benjamin.george@bowmanfurniture.com", "paul@bowmanfurniture.com" ], "cc_mail_ids": [ "accounts@bowmanfurniture.com" ], "subject": "Invoice for the subscription.", "body": "Please find attached invoice for your subscription." }

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Your invoice has been sent." }

ARGUMENTS

to_mail_ids
Required
The email IDs to which the invoice is to be mailed.
cc_mail_ids
Optional
The email IDs that have to be copied when the credit note is to be mailed.
subject
Required
The subject of the email.
body
Required
The body of the email.

Write off

Write off a payment.

POST /invoices/{invoice_id}/writeoff

Request Example

  
$ curl https://subscriptions.zoho.com/api/v1/invoices/{invoice_id}/writeoff -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "X-com-zoho-subscriptions-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Payment has been written off." }

Cancel Write off

Revert write off performed for a payment

POST /invoices/{invoice_id}/cancelwriteoff

Request Example

  
$ curl https://subscriptions.zoho.com/api/v1/invoices/{invoice_id}/cancelwriteoff -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "X-com-zoho-subscriptions-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The write off performed for this payment has been cancelled." }

Update address

Update shipping and billing address of an invoice

PUT /invoices/{invoice_id}/address

Request Example

  
$ curl https://subscriptions.zoho.com/api/v1/invoices/{invoice_id}/address -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "X-com-zoho-subscriptions-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8" -d '{ "billing_address": { "city": "Salt Lake City", "state": "CA", "zip": 92612, "country": "U.S.A", "fax": 4527389 }, "shipping_address": { "city": "Salt Lake City", "state": "CA", "zip": 92612, "country": "U.S.A", "fax": 4527389 } }

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Invoice address updated", "invoice_address": { "billing_address": { "city": "Salt Lake City", "state": "CA", "zip": 92612, "country": "U.S.A", "fax": 4527389 }, "shipping_address": { "city": "Salt Lake City", "state": "CA", "zip": 92612, "country": "U.S.A", "fax": 4527389 } } }

ARGUMENTS

billing_address
Optional
Customer's billing address object. It contains street, city, state,zip and country.
city
Optional
Name of the city of the customer's billing address.
state
Optional
Name of the state of the customer's billing address.
zip
Optional
Zip code of the customer's billing address.
country
Optional
Name of the country of the customer's billing address.
fax
Optional
Customer's fax number.
shipping_address
Optional
Customer's shipping address object. It contains street, city, state,zip and country.
city
Optional
Name of the city of the customer's billing address.
state
Optional
Name of the state of the customer's billing address.
zip
Optional
Zip code of the customer's billing address.
country
Optional
Name of the country of the customer's billing address.
fax
Optional
Customer's fax number.

Update Custom Fields

Update the custom fields of an invoice

POST /invoices/{invoice_id}/customfields

Request Example

  
$ curl https://subscriptions.zoho.com/api/v1/invoices/{invoice_id}/customfields -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "X-com-zoho-subscriptions-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8" -d '{ "custom_fields": [ { "label": "label", "value": 129890 } ] }

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Invoice address updated", "data": { "custom_fields": [ { "index": 1, "value": 129890, "label": "label", "data_type": "text" } ] } }

ARGUMENTS

custom_fields
Required
Additional fields for the invoices.
label
Required
Label of the custom field.
value
Required
Value of the custom field.

Payments

A payment object describes details regarding a particular customer payment. There can be multiple payments for a single invoice. Multiple invoices can be paid in a single payment as well.

Example

{ "payment_id": "9030000079467", "payment_mode": "cash", "amount": 450, "amount_refunded": 50, "date": "2016-06-05", "status": "success", "reference_number": "INV-384", "description": "Payment has been added to INV-384", "customer_id": "903000000000099", "customer_name": "Bowman Furniture", "email": "benjamin.george@bowmanfurniture.com", "autotransaction": { "autotransaction_id": "90300000079465", "payment_gateway": "payflow_pro", "gateway_transaction_id": "B10E6E0F31BD", "gateway_error_message": "Gateway error message for a failed transaction.", "card_id": "90300000079226", "last_four_digits": 1111, "expiry_month": 9, "expiry_year": 2030 }, "invoices": [ { "invoice_id": "90300000079426", "invoice_number": "INV-384", "date": "2016-06-05", "invoice_amount": 450, "amount_applied": 450, "balance_amount": 0 } ], "currency_code": "USD", "currency_symbol": "$", "exchange_rate": 1, "bank_charges": 10, "tax_account_id": "903000000000370", "account_id": "903000000000361", "custom_fields": [ { "value": 129890, "label": "label", "data_type": "text" } ] }

Attribute

payment_id
string
Unique ID of the payment generated by the server.
payment_mode
string
Mode through which payment is made. This can be check, cash, creditcard, banktransfer, bankremittance, autotransaction or others.
amount
double
Amount paid in the respective payment.
amount_refunded
double
Amount that is refund. Refunds are applicable only for payments whose payment_mode is autotransaction. Refunds would be made to the respective card provided by the customer.
date
string
Date on which payment is made.
status
string
Status of the payment. It can either be success or failure.
reference_number
string
Reference number generated for the payment. A string of your choice can also be used as the reference number.
description
string
Description about the payment.
customer_id
string
Customer ID of the customer involved in the payment.
customer_name
string
Name of the customer to whom the invoice is raised.
email
string
Email address of the customer involved in the payment.
autotransaction
object
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.
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 provided by the gateway for the transaction.
gateway_error_message
string
Gateway error message for a failed transaction.
card_id
string
Card ID of the card associated with the transaction.
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.
list
List of invoices associated with the payment. Each invoice object contains invoice_id, invoice_number, date, invoice_amount, amount_applied and balance_amount.
invoice_id
string
Invoice ID of the required invoice.
invoice_number
string
Unique ID (starts with INV) of an invoice.
date
string
Date on which payment is made.
invoice_amount
double
Total amount raised for the invoice.
amount_applied
double
Amount paid for the invoice.
balance_amount
double
Unpaid amount of the invoice.
currency_code
string
Currency code in which the payment is made.
currency_symbol
string
Customer's currency symbol.
exchange_rate
double
Exchange rate for the currency used in the invoices and customer's currency. The payment amount would be the multiplicative product of the original amount and the exchange rate.
bank_charges
double
Denotes any additional bank charges.
tax_account_id
string
Unique ID of the account which was used for transaction.
account_id
string
Unique ID of the account.
custom_fields
list
Additional fields for the payments.
value
string
Value of the custom field.
label
string
Label of the custom field.
data_type
string
Data type of the custom field.

Create a payment

Create a new payment.

POST /payments

Request Example

  
$ curl https://subscriptions.zoho.com/api/v1/payments -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "X-com-zoho-subscriptions-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8" -d '{ "customer_id": "903000000000099", "payment_mode": "cash", "amount": 450, "date": "2016-06-05", "reference_number": "INV-384", "description": "Payment has been added to INV-384", "invoices": [ { "invoice_id": "90300000079426", "amount_applied": 450 } ], "exchange_rate": 1, "bank_charges": 10, "tax_account_id": "903000000000370", "account_id": "903000000000361", "custom_fields": [ { "label": "label", "value": 129890 } ] }

Response Example

  
HTTP/1.1 201 Created Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The payment has been created.", "payment": { "payment_id": "9030000079467", "payment_mode": "cash", "amount": 450, "amount_refunded": 50, "bank_charges": 10, "date": "2016-06-05", "status": "success", "reference_number": "INV-384", "description": "Payment has been added to INV-384", "customer_id": "903000000000099", "customer_name": "Bowman Furniture", "email": "benjamin.george@bowmanfurniture.com", "autotransaction": { "autotransaction_id": "90300000079465", "payment_gateway": "payflow_pro", "gateway_transaction_id": "B10E6E0F31BD", "gateway_error_message": "Gateway error message for a failed transaction.", "card_id": "90300000079226", "last_four_digits": 1111, "expiry_month": 9, "expiry_year": 2030 }, "invoices": [ { "invoice_id": "90300000079426", "invoice_number": "INV-384", "date": "2016-06-05", "invoice_amount": 450, "amount_applied": 450, "balance_amount": 0 } ], "currency_code": "USD", "currency_symbol": "$", "custom_fields": [ { "index": 1, "value": 129890, "label": "label", "data_type": "text" } ] } }

ARGUMENTS

customer_id
Required
Customer ID of the customer involved in the payment.
payment_mode
Required
Mode through which payment is made. This can be check, cash, creditcard, banktransfer, bankremittance, autotransaction or others.
amount
Required
Amount paid in the respective payment.
date
Optional
Date on which payment is made.
reference_number
Optional
Reference number generated for the payment. A string of your choice can also be used as the reference number.
description
Optional
Description about the payment.
Required
List of invoices associated with the payment. Each invoice object contains invoice_id, invoice_number, date, invoice_amount, amount_applied and balance_amount.
invoice_id
Required
Invoice ID of the required invoice.
amount_applied
Required
Amount paid for the invoice.
exchange_rate
Optional , default is 1
Exchange rate for the currency used in the invoices and customer's currency. The payment amount would be the multiplicative product of the original amount and the exchange rate.
bank_charges
Optional
Denotes any additional bank charges.
tax_account_id
Optional
Unique ID of the account which was used for transaction.
account_id
Optional
Unique ID of the account.
custom_fields
Optional
Additional fields for the payments.
label
Optional
Label of the custom field.
value
Optional
Value of the custom field.

Retrieve a payment

Details of an existing payment.

GET /payments/{payment_id}

Request Example

  
$ curl https://subscriptions.zoho.com/api/v1/payments/{payment_id} -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "X-com-zoho-subscriptions-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "payment": { "payment_id": "9030000079467", "payment_mode": "cash", "amount": 450, "amount_refunded": 50, "bank_charges": 10, "date": "2016-06-05", "status": "success", "reference_number": "INV-384", "description": "Payment has been added to INV-384", "customer_id": "903000000000099", "customer_name": "Bowman Furniture", "email": "benjamin.george@bowmanfurniture.com", "autotransaction": { "autotransaction_id": "90300000079465", "payment_gateway": "payflow_pro", "gateway_transaction_id": "B10E6E0F31BD", "gateway_error_message": "Gateway error message for a failed transaction.", "card_id": "90300000079226", "last_four_digits": 1111, "expiry_month": 9, "expiry_year": 2030 }, "invoices": [ { "invoice_id": "90300000079426", "invoice_number": "INV-384", "date": "2016-06-05", "invoice_amount": 450, "amount_applied": 450, "balance_amount": 0 } ], "currency_code": "USD", "currency_symbol": "$", "custom_fields": [ { "index": 1, "value": 129890, "label": "label", "data_type": "text" } ] } }

Update a payment

Update an existing payment information.

PUT /payments/{payment_id}

Request Example

  
$ curl https://subscriptions.zoho.com/api/v1/payments/{payment_id} -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "X-com-zoho-subscriptions-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8" -d '{ "customer_id": "903000000000099", "payment_mode": "cash", "amount": 450, "date": "2016-06-05", "reference_number": "INV-384", "description": "Payment has been added to INV-384", "invoices": [ { "invoice_id": "90300000079426", "amount_applied": 450 } ], "exchange_rate": 1, "bank_charges": 10, "tax_account_id": "903000000000370", "account_id": "903000000000361", "custom_fields": [ { "label": "label", "value": 129890 } ] }

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The payment details have been updated.", "payment": { "payment_id": "9030000079467", "payment_mode": "cash", "amount": 450, "amount_refunded": 50, "bank_charges": 10, "date": "2016-06-05", "status": "success", "reference_number": "INV-384", "description": "Payment has been added to INV-384", "customer_id": "903000000000099", "customer_name": "Bowman Furniture", "email": "benjamin.george@bowmanfurniture.com", "autotransaction": { "autotransaction_id": "90300000079465", "payment_gateway": "payflow_pro", "gateway_transaction_id": "B10E6E0F31BD", "gateway_error_message": "Gateway error message for a failed transaction.", "card_id": "90300000079226", "last_four_digits": 1111, "expiry_month": 9, "expiry_year": 2030 }, "invoices": [ { "invoice_id": "90300000079426", "invoice_number": "INV-384", "date": "2016-06-05", "invoice_amount": 450, "amount_applied": 450, "balance_amount": 0 } ], "currency_code": "USD", "currency_symbol": "$", "custom_fields": [ { "index": 1, "value": 129890, "label": "label", "data_type": "text" } ] } }

ARGUMENTS

customer_id
Required
Customer ID of the customer involved in the payment.
payment_mode
Required
Mode through which payment is made. This can be check, cash, creditcard, banktransfer, bankremittance, autotransaction or others.
amount
Required
Amount paid in the respective payment.
date
Optional
Date on which payment is made.
reference_number
Optional
Reference number generated for the payment. A string of your choice can also be used as the reference number.
description
Optional
Description about the payment.
Required
List of invoices associated with the payment. Each invoice object contains invoice_id, invoice_number, date, invoice_amount, amount_applied and balance_amount.
invoice_id
Required
Invoice ID of the required invoice.
amount_applied
Required
Amount paid for the invoice.
exchange_rate
Optional , default is 1
Exchange rate for the currency used in the invoices and customer's currency. The payment amount would be the multiplicative product of the original amount and the exchange rate.
bank_charges
Optional
Denotes any additional bank charges.
tax_account_id
Optional
Unique ID of the account which was used for transaction.
account_id
Optional
Unique ID of the account.
custom_fields
Optional
Additional fields for the payments.
label
Optional
Label of the custom field.
value
Optional
Value of the custom field.

Delete a payment

Delete an existing payment.

DELETE /payments/{payment_id}

Request Example

  
$ curl https://subscriptions.zoho.com/api/v1/payments/{payment_id} -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "X-com-zoho-subscriptions-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The payment has been deleted." }

Credit-Notes

Credit notes are created when a refund is to be made to a customer. A credit note object allows you to keep track of all credit note related information.

Example

{ "creditnote_id": "90300000072369", "creditnote_number": "CN-29", "ignore_auto_number_generation": false, "date": "2016-06-05", "status": "open", "customer_id": "903000000000099", "customer_name": "Bowman Furniture", "custom_fields": [ { "value": 129890, "label": "label", "data_type": "text" } ], "reference_number": "INV-384", "email": "benjamin.george@bowmanfurniture.com", "total": 450, "balance": 10, "creditnote_items": [ { "item_id": "90300000081501", "description": "prorated amount for items", "code": "basic-monthly", "name": "Basic Monthly", "type": 1, "account_id": "903000000000388", "account_name": "Sales", "quantity": 1, "tax_id": "903000000000356", "price": 100, "item_total": 100 } ], "invoices": [ { "invoice_id": "90300000079426", "invoice_number": "INV-384", "amount": 450 } ], "currency_code": "USD", "currency_symbol": "$", "created_time": "2016-06-05T02:30:08-0700", "updated_time": "2016-06-05T02:30:08-0700", "template_id": "90300000001336", "template_name": "Standard Template" }

Attribute

creditnote_id
string
Unique ID of the credit note generated by the server.
creditnote_number
string
Unique number generated (starts with CN) which will be displayed in the interface and credit notes.
ignore_auto_number_generation
boolean
Set to true if you need to provide your own credit note number.
date
string
The date on which credit note is raised.
status
string
Status of the credit note. This can be open, closed or void.
customer_id
string
Customer ID of the customer for whom the credit note is raised.
customer_name
string
Name of the customer to whom the credit note is raised.
custom_fields
list
Additional fields for the Credit-Notes.
value
string
Value of the custom field.
label
string
Label of the custom field.
data_type
string
Data type of the custom field.
reference_number
string
Reference number generated for the payment. A string of your choice can also be used as the reference number.
email
string
Email address of the customer.
total
double
Total credits raised in this credit note.
balance
double
The unapplied credits.
creditnote_items
list
List of items involved in the credit note. This contains item_id, description, quantity, price and item_total.
item_id
string
Unique string generated for the item to which a refund is to be made.
code
string
Unique code for the creditnote line item.
name
string
Name of the credit
account_id
string
Unique ID to denote the account.
account_name
string
Name of the account.
quantity
required
Quantity of the item included.
tax_id
string
Unique to denote the tax associate dto the creditnote
price
double
The price of the item included.
item_total
double
Total credits raised by this item. This would be the multiplicative product of item price and quantity.
list
List of invoices for which the credit note has been raised. This contains invoice_id and amount.
invoice_id
string
Invoice ID of the required invoice.
invoice_number
string
Invoice number of the required invoice.
amount
double
Amount paid for the invoice.
currency_code
string
Customer's currency code. This currency code is used in credit notes.
currency_symbol
string
Customer's currency symbol.
created_time
string
Time at which the credit note was created.
updated_time
string
Time at which the credit note details were last updated.
template_id
string
Unique ID of the creditnote template
template_name
string
Name of the default template of the creditnote.

Create a credit note

Details of an existing creditnote.

POST /creditnotes

Request Example

  
$ curl https://subscriptions.zoho.com/api/v1/creditnotes -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "X-com-zoho-subscriptions-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8" -d '{ "customer_id": "903000000000099", "contact_persons": [ "903000006532" ], "date": "2016-06-05", "exchange_rate": "5.5", "creditnote_items": [ { "description": "prorated amount for items", "code": "basic-monthly", "account_id": "903000000000388", "quantity": 1, "tax_id": "903000000000356", "tax_exemption_id": "903000006345", "tax_exemption_code": "GST FREE", "price": 100 } ], "creditnote_number": "CN-29", "ignore_auto_number_generation": false, "reference_number": "INV-384", "custom_fields": [ { "label": "label", "value": 129890 } ], "notes": "Offer for the referral", "terms": "", "template_id": "90300000001336" }

Response Example

  
HTTP/1.1 201 Created Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Credit Note created successfully.", "credit_note": { "creditnote_id": "90300000072369", "creditnote_number": "CN-29", "date": "2016-06-05", "status": "open", "customer_id": "903000000000099", "customer_name": "Bowman Furniture", "custom_fields": [ { "index": 1, "value": 129890, "label": "label", "data_type": "text" } ], "reference_number": "INV-384", "email": "benjamin.george@bowmanfurniture.com", "total": 450, "balance": 10, "creditnote_items": [ { "item_id": "90300000081501", "description": "prorated amount for items", "code": "basic-monthly", "name": "Basic Monthly", "type": 1, "account_id": "903000000000388", "account_name": "Sales", "quantity": 1, "tax_id": "903000000000356", "price": 100, "item_total": 100 } ], "invoices": [ { "invoice_id": "90300000079426", "invoice_number": "INV-384", "amount": 450 } ], "taxes": [ { "tax_id": "903000000000356", "tax_name": "Basic Tax", "tax_amount": "2.50" } ], "currency_code": "USD", "currency_symbol": "$", "created_time": "2016-06-05T02:30:08-0700", "updated_time": "2016-06-05T02:30:08-0700", "template_id": "90300000001336", "template_name": "Standard Template", "notes": "Offer for the referral", "terms": "" } }

ARGUMENTS

customer_id
Required
Customer ID of the customer for whom the credit note is raised.
contact_persons
Optional
Contact Persons associated with the credit note.
date
Required
The date on which credit note is raised.
exchange_rate
Optional
Exchange rate for the currency associated with the customer.
creditnote_items
Required
List of items involved in the credit note. This contains item_id, description, quantity, price and item_total.
code
Required
Unique code for the creditnote line item.
account_id
Optional
Unique ID to denote the account.
quantity
Required
Quantity of the item included.
tax_id
Optional
Unique to denote the tax associate dto the creditnote
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.
price
Required
The price of the item included.
creditnote_number
Required
Unique number generated (starts with CN) which will be displayed in the interface and credit notes.
ignore_auto_number_generation
Optional
Set to true if you need to provide your own credit note number.
reference_number
Optional
Reference number generated for the payment. A string of your choice can also be used as the reference number.
custom_fields
Optional
Additional fields for the Credit-Notes.
label
Optional
Label of the custom field.
value
Optional
Value of the custom field.
notes
Optional
A short note for the credit note.
terms
Optional
Terms & condition to be displayed in the credit note.
template_id
Optional
Unique ID of the creditnote template

Retreive a credit note

Details of an existing creditnote.

GET /creditnotes/{creditnote_id}

Request Example

  
$ curl https://subscriptions.zoho.com/api/v1/creditnotes/{creditnote_id} -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "X-com-zoho-subscriptions-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "credit_note": { "creditnote_id": "90300000072369", "creditnote_number": "CN-29", "date": "2016-06-05", "status": "open", "customer_id": "903000000000099", "customer_name": "Bowman Furniture", "custom_fields": [ { "index": 1, "value": 129890, "label": "label", "data_type": "text" } ], "reference_number": "INV-384", "email": "benjamin.george@bowmanfurniture.com", "total": 450, "balance": 10, "creditnote_items": [ { "item_id": "90300000081501", "description": "prorated amount for items", "code": "basic-monthly", "name": "Basic Monthly", "type": 1, "account_id": "903000000000388", "account_name": "Sales", "quantity": 1, "tax_id": "903000000000356", "price": 100, "item_total": 100 } ], "invoices": [ { "invoice_id": "90300000079426", "invoice_number": "INV-384", "amount": 450 } ], "taxes": [ { "tax_id": "903000000000356", "tax_name": "Basic Tax", "tax_amount": "2.50" } ], "currency_code": "USD", "currency_symbol": "$", "created_time": "2016-06-05T02:30:08-0700", "updated_time": "2016-06-05T02:30:08-0700", "template_id": "90300000001336", "template_name": "Standard Template", "notes": "Offer for the referral", "terms": "" } }

Email a credit note

Email a credit note.

POST /creditnotes/{creditnote_id}/email

Request Example

  
$ curl https://subscriptions.zoho.com/api/v1/creditnotes/{creditnote_id}/email -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "X-com-zoho-subscriptions-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8" -d '{ "to_mail_ids": [ "benjamin.george@bowmanfurniture.com", "paul@bowmanfurniture.com" ], "cc_mail_ids": [ "accounts@bowmanfurniture.com" ], "subject": "Credit note for subscription.", "body": "Please find attached the credit note for your subscription." }

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Your creditnote has been sent." }

ARGUMENTS

to_mail_ids
Required
The email IDs to which the credit note is to be mailed.
cc_mail_ids
Optional
The email IDs that have to be copied when the credit note is to be mailed.
subject
Required
The subject of the email.
body
Required
The body of the email.

Void a credit note

Details of an existing creditnote.

POST /creditnotes/{creditnote_id}/void

Request Example

  
$ curl https://subscriptions.zoho.com/api/v1/creditnotes/{creditnote_id}/void -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "X-com-zoho-subscriptions-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The credit note has been marked as void." }

Open a voided credit note

Convert a voided credit note to open

POST /creditnotes/{creditnote_id}/converttoopen

Request Example

  
$ curl https://subscriptions.zoho.com/api/v1/creditnotes/{creditnote_id}/converttoopen -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "X-com-zoho-subscriptions-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Status of the credit note has been changed to open." }

Delete a credit note

Delete an existing credit note

DELETE /creditnotes/{creditnote_id}

Request Example

  
$ curl https://subscriptions.zoho.com/api/v1/creditnotes/{creditnote_id} -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "X-com-zoho-subscriptions-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The credit note has been deleted." }

Refunds

A refund object enables you to manage your refunds. Refunds can be made by direct payment to the respective customer or through credits.

Example

{ "refund_id": "90300000081385", "date": "2016-06-05", "amount": "20", "description": "Refund for discount Offer", "reference_number": "INV-384", "refund_mode": "autotransaction", "status": "success", "customer_id": "903000000000099", "email": "benjamin.george@bowmanfurniture.com", "creditnote": { "creditnote_id": "90300000081375", "creditnote_number": "CN-26", "date": "2016-06-05", "amount": "20", "refund_amount": 20, "balance_amount": 0 }, "autotransaction": { "autotransaction_id": "9030000081373", "payment_gateway": "Paypal Payflowpro", "gateway_transaction_id": "B70E6CCF288D", "gateway_error_message": "Gateway error for a failed transaction.", "card_id": "903000079226", "last_four_digits": 1111, "expiry_month": 9, "expiry_year": 2030 }, "currency_code": "USD", "currency_symbol": "$" }

Attribute

refund_id
string
Unique ID generated for a refund made.
date
string
The date on which refund is made.
amount
double
The amount to be refund.
description
string
A small description about the refund.
reference_number
string
Reference number for the refund made. A custom string can also be set as the reference number.
refund_mode
string
Mode through which refund is made. This can be check, cash, creditcard, banktransfer, bankremittance, autotransaction or others.
status
string
Status of the refund made. This can be either success or failure.
customer_id
string
Customer ID of the customer to whom the refund is to be made.
email
string
Email address of the customer.
object
It contains details of the credit note for which the refund has to made. Each object contains creditnote_id, creditnote_number, date, amount, refund_amount and balance_amount.
creditnote_id
string
Credit note ID of the credit note involved in this refund.
creditnote_number
string
Credit note number (starts with CN) of the credit note.
date
string
The date on which refund is made.
amount
double
The amount to be refund.
refund_amount
double
The amount for which the refund is to be made.
balance_amount
double
Unused credits.
autotransaction
object
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.
currency_symbol
string
The currency symbol of the currency chosen for the customer.

Refund a credit note

Refund is made on the credit note.

POST /creditnotes/{creditnote_id}/refunds

Request Example

  
$ curl https://subscriptions.zoho.com/api/v1/creditnotes/{creditnote_id}/refunds -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "X-com-zoho-subscriptions-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8" -d '{ "amount": "20", "description": "Refund for discount Offer" }

Response Example

  
HTTP/1.1 201 Created Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The refund information has been saved.", "refund": { "refund_id": "90300000081385", "date": "2016-06-05", "amount": "20", "description": "Refund for discount Offer", "reference_number": "INV-384", "refund_mode": "autotransaction", "status": "success", "customer_id": "903000000000099", "email": "benjamin.george@bowmanfurniture.com", "creditnote": { "creditnote_id": "90300000081375", "creditnote_number": "CN-26", "date": "2016-06-05", "amount": "20", "refund_amount": 20, "balance_amount": 0 }, "autotransaction": { "autotransaction_id": "9030000081373", "payment_gateway": "Paypal Payflowpro", "gateway_transaction_id": "B70E6CCF288D", "gateway_error_message": "Gateway error for a failed transaction.", "card_id": "903000079226", "last_four_digits": 1111, "expiry_month": 9, "expiry_year": 2030 }, "currency_code": "USD", "currency_symbol": "$" } }

ARGUMENTS

amount
Required
The amount to be refund.
description
Optional
A small description about the refund.

Refund a payment

A new credit note is created for the amount to be refund. Refund is then made for the credit note.

POST /payments/{payment_id}/refunds

Request Example

  
$ curl https://subscriptions.zoho.com/api/v1/payments/{payment_id}/refunds -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "X-com-zoho-subscriptions-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8" -d '{ "amount": "20", "description": "Refund for discount Offer" }

Response Example

  
HTTP/1.1 201 Created Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "The refund information has been saved.", "refund": { "refund_id": "90300000081385", "date": "2016-06-05", "amount": "20", "description": "Refund for discount Offer", "reference_number": "INV-384", "refund_mode": "autotransaction", "status": "success", "customer_id": "903000000000099", "email": "benjamin.george@bowmanfurniture.com", "creditnote": { "creditnote_id": "90300000081375", "creditnote_number": "CN-26", "date": "2016-06-05", "amount": "20", "refund_amount": 20, "balance_amount": 0 }, "autotransaction": { "autotransaction_id": "9030000081373", "payment_gateway": "Paypal Payflowpro", "gateway_transaction_id": "B70E6CCF288D", "gateway_error_message": "Gateway error for a failed transaction.", "card_id": "903000079226", "last_four_digits": 1111, "expiry_month": 9, "expiry_year": 2030 }, "currency_code": "USD", "currency_symbol": "$" } }

ARGUMENTS

amount
Required
The amount to be refund.
description
Optional
A small description about the refund.

Retrieve refund details

Details of an existing refund.

GET /creditnotes/refunds/{refund_id}

Request Example

  
$ curl https://subscriptions.zoho.com/api/v1/creditnotes/refunds/{refund_id} -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "X-com-zoho-subscriptions-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "refund": { "refund_id": "90300000081385", "date": "2016-06-05", "amount": "20", "description": "Refund for discount Offer", "reference_number": "INV-384", "refund_mode": "autotransaction", "status": "success", "customer_id": "903000000000099", "email": "benjamin.george@bowmanfurniture.com", "creditnote": { "creditnote_id": "90300000081375", "creditnote_number": "CN-26", "date": "2016-06-05", "amount": "20", "refund_amount": 20, "balance_amount": 0 }, "autotransaction": { "autotransaction_id": "9030000081373", "payment_gateway": "Paypal Payflowpro", "gateway_transaction_id": "B70E6CCF288D", "gateway_error_message": "Gateway error for a failed transaction.", "card_id": "903000079226", "last_four_digits": 1111, "expiry_month": 9, "expiry_year": 2030 }, "currency_code": "USD", "currency_symbol": "$" } }

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.

Example

{ "hostedpage_id": "8c589071e7e26a8d28e8af081c373fb00bd6dc5366fd129eefd5c61c569da526", "status": "success", "url": "https://subscriptions.zoho.com/hostedpage/8c589071e7e26a8d28e8af081c373fb00bd6dc5366fd129eefd5c61c569da526/checkout", "action": "new_subscription", "expiring_time": "2016-06-05T00:11:16-0700", "created_time": "2016-06-05T23:10:16-0700" }

Attribute

hostedpage_id
string
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.

GET /hostedpages/{hostedpage_id}

Request Example

  
$ curl https://subscriptions.zoho.com/api/v1/hostedpages/{hostedpage_id} -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "X-com-zoho-subscriptions-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": "0", "message": "success", "hostedpage_id": "8c589071e7e26a8d28e8af081c373fb00bd6dc5366fd129eefd5c61c569da526", "status": "success", "url": "https://subscriptions.zoho.com/hostedpage/8c589071e7e26a8d28e8af081c373fb00bd6dc5366fd129eefd5c61c569da526/checkout", "action": "new_subscription", "expiring_time": "2016-06-05T00:11:16-0700", "created_time": "2016-06-05T23:10:16-0700", "custom_fields": [ { "index": 1, "label": "label", "value": "129890", "data_type": "string" } ], "data": { "subscription": { "subscription_id": "9030000079200", "name": "GatorHost-Basic", "status": "success", "amount": 186, "created_at": "2016-06-05", "current_term_starts_at": "2016-06-01", "current_term_ends_at": "2016-06-30", "next_billing_at": "2016-06-30", "expires_at": "2015-06-01", "interval": 1, "interval_unit": "months", "auto_collect": true, "created_time": "2016-06-05T23:10:16-0700", "updated_time": "2016-07-04T16:44:15-0700", "reference_id": "bowmanfurniture", "salesperson_id": "9877000000058001", "salesperson_name": "Franklin", "child_invoice_id": "90300000079210", "pricebook_id": "90300000070987", "currency_code": "CAD", "currency_symbol": "$", "end_of_term": true, "product_id": "9030000079065", "product_name": "Bowman Furniture", "plan": { "plan_code": "basic-monthly", "name": "GatorHost-Basic", "quantity": 1, "price": 20, "discount": 20, "total": 50, "setup_fee": 20, "description": "Monthly Basic plan.", "tax_id": "90300000023123", "exclude_trial": false, "exclude_setup_fee": false, "trial_days": 0 }, "addons": [ { "addon_code": "Email-basic", "name": "GatorHost-Basic", "description": "Monthly Basic plan.", "quantity": 1, "price": 20, "discount": 20, "total": 50, "tax_id": "90300000023123" } ], "taxes": [ {...} ], "coupon": { "coupon_code": "Flat10", "discount_amount": 44 }, "card": { "card_id": "90300000766098", "last_four_digits": "2145", "payment_gateway": "payflow_pro", "expiry_month": 9, "expiry_year": 2030 }, "payment_terms": 1, "payment_terms_label": "Due On Receipt", "can_add_bank_account": true, "customer": { "customer_id": "903000000000099", "display_name": "Bowman Furniture", "first_name": "Benjamin", "last_name": "George", "email": "benjamin.george@bowmanfurniture.com", "company_name": "Bowman Furniture", "billing_address": { "street": "Harrington Bay Street", "city": "Salt Lake City", "state": "CA", "country": "U.S.A", "zip": "92612", "fax": "4527389" }, "shipping_address": { "street": "Harrington Bay Street", "city": "Salt Lake City", "state": "CA", "zip": "92612", "country": "U.S.A", "fax": "4527389" }, "payment_terms": 1, "payment_terms_label": "Due On Receipt" }, "custom_fields": [ { "index": 1, "label": "label", "value": "129890", "data_type": "string" } ], "contactpersons": [ { "contactperson_id": "903000000000099" } ], "notes": [ { "note_id": "90300006700232", "description": "Monthly Basic plan.", "commented_by": "Benjamin", "commented_time": "2016-06-11T17:57:13-0700" } ], "payment_gateways": [ { "payment_gateway": "payflow_pro" } ] }, "invoice": { "invoice_id": "90300000079426", "number": "INV-384", "status": "success", "invoice_date": "2016-06-15", "due_date": "2016-06-15", "payment_expected_date": "10-05-2013", "ach_payment_initiated": true, "transaction_type": "invoice", "customer_id": "903000000000099", "customer_name": "Benjamin", "email": "benjamin.george@bowmanfurniture.com", "invoice_items": [ { "item_id": "90300000079434", "name": "GatorHost-Basic", "description": "Monthly Basic plan.", "code": "0", "price": 20, "quantity": 1, "discount_amount": 44, "item_total": 400, "tax_id": "90300000023123", "tax_exemption_id": "903000006345", "tax_exemption_code": "GST FREE" } ], "coupon": { "coupon_code": "Flat10", "discount_amount": 44 }, "credits": {...}, "total": 50, "payment_made": 370, "balance": 0, "credits_applied": 0, "write_off_amount": 0, "payments": [ { "payment_id": "9030000079467", "payment_mode": "autotransaction", "invoice_payment_id": "90300000079469", "gateway_transaction_id": "B10E6E0F31BD", "description": "Monthly Basic plan.", "date": "2016-06-05", "reference_number": "INV-384", "amount": 186, "exchange_rate": 2 } ], "currency_code": "CAD", "currency_symbol": "$", "created_time": "2016-06-05T23:10:16-0700", "updated_time": "2016-07-04T16:44:15-0700", "salesperson_id": "9877000000058001", "salesperson_name": "Franklin", "invoice_url": "", "billing_address": { "attention": "Benjamin George", "street": "Harrington Bay Street", "city": "Salt Lake City", "state": "CA", "country": "U.S.A", "zip": "92612", "fax": "4527389" }, "shipping_address": { "attention": "Benjamin George", "street": "Harrington Bay Street", "city": "Salt Lake City", "state": "CA", "country": "U.S.A", "zip": "92612", "fax": "4527389" }, "comments": [ { "comment_id": "90300000003133", "description": "Monthly Basic plan.", "commented_by_id": "90300003002099", "commented_by": "Benjamin", "comment_type": "system", "date": "2016-06-05", "time": "2016-06-11T17:57:13-0700", "operation_type": "add", "transaction_id": "90300000079467", "transaction_type": "invoice" } ], "custom_fields": [ { "index": 1, "label": "label", "value": "129890", "data_type": "string" } ] } } }

List of HostedPages

Retrieve the list of all hosted pages.

GET /hostedpages

Request Example

  
$ curl https://subscriptions.zoho.com/api/v1/hostedpages -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "X-com-zoho-subscriptions-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "hosted_pages": [ { "hostedpage_id": "8c589071e7e26a8d28e8af081c373fb00bd6dc5366fd129eefd5c61c569da526", "status": "success", "url": "https://subscriptions.zoho.com/hostedpage/8c589071e7e26a8d28e8af081c373fb00bd6dc5366fd129eefd5c61c569da526/checkout", "action": "new_subscription", "expiring_time": "2016-06-05T00:11:16-0700", "created_time": "2016-06-05T23:10:16-0700" }, {...}, {...} ] }

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.

POST /hostedpages/newsubscription

Request Example

  
$ curl https://subscriptions.zoho.com/api/v1/hostedpages/newsubscription -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "X-com-zoho-subscriptions-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8" -d '{ "customer": { "display_name": "Bowman Furniture", "salutation": "Mr.", "first_name": "Benjamin", "last_name": "George", "email": "benjamin.george@bowmanfurniture.com", "company_name": "Bowman Furniture", "billing_address": { "attention": "Benjamin George", "street": "Harrington Bay Street", "city": "Salt Lake City", "state": "CA", "country": "U.S.A", "zip": "92612", "fax": "4527389" }, "shipping_address": { "attention": "Benjamin George", "street": "Harrington Bay Street", "city": "Salt Lake City", "state": "CA", "country": "U.S.A", "zip": "92612", "fax": "4527389" }, "payment_terms": 1, "payment_terms_label": "Due On Receipt", "exchange_rate": 2, "currency_code": "CAD", "vat_treatment": "non_eu", "vat_reg_no": 51423456782, "country_code": "DE", "is_taxable": true, "tax_id": "90300000023123", "tax_authority_id": "903000006345", "tax_authority_name": "ATO", "tax_exemption_id": "903000006345", "tax_exemption_code": "GST FREE", "default_templates": { "invoice_template_id": "90300000311340", "creditnote_template_id": "90300000232140" }, "place_of_contact": "TN", "gst_no": "33AAAAA0000A1Z5", "gst_treatment": "business_gst" }, "contactpersons": [ { "contactperson_id": "903000000000099" } ], "plan": { "plan_code": "basic-monthly", "plan_description": "Monthly Basic plan", "price": 20, "setup_fee": 20, "setup_fee_tax_id": "9030000123123", "quantity": 1, "tax_id": "90300000023123", "tax_exemption_id": "903000006345", "tax_exemption_code": "GST FREE", "setup_fee_tax_exemption_id": "9030000123098", "setup_fee_tax_exemption_code": "GST FREE", "exclude_trial": false, "exclude_setup_fee": false, "billing_cycles": -1, "trial_days": 0 }, "addons": [ { "addon_code": "Email-basic", "addon_description": "Monthly addon.", "price": 20, "quantity": 1, "tax_id": "90300000023123", "tax_exemption_id": "903000006345", "tax_exemption_code": "GST FREE" } ], "reference_id": "bowmanfurniture", "additional_param": "new_subscription", "starts_at": "2016-06-05", "custom_fields": [ { "label": "label", "value": "129890" } ], "coupon_code": "Flat10", "redirect_url": "http://www.zillum.com/products/piperhost", "salesperson_name": "Franklin" }

Response Example

  
HTTP/1.1 201 Created Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Hosted page has been created successfully.", "hostedpage": { "hostedpage_id": "8c589071e7e26a8d28e8af081c373fb00bd6dc5366fd129eefd5c61c569da526", "status": "success", "url": "https://subscriptions.zoho.com/hostedpage/8c589071e7e26a8d28e8af081c373fb00bd6dc5366fd129eefd5c61c569da526/checkout", "action": "new_subscription", "expiring_time": "2016-06-05T00:11:16-0700", "created_time": "2016-06-05T23:10:16-0700" } }

ARGUMENTS

customer_id
Required for creating a hostedpage for existing customer.
Customer ID of the customer for whom a subscription needs to be created.
Required for creating a subscription for new customer.
Customer object of the customer for whom you want to create a subscription. Each object contains display_name, company_name, first_name, last_name, email, fax, currency_code and billing_address.
display_name
Required
This will be name which will be displayed in the interface and invoices.
salutation
Optional
Salutation of the customer.
first_name
Optional
First name of the customer.
last_name
Optional
Last name of the customer.
email
Required
Email address of the customer.
company_name
Optional
Registered name of the company the customer represents.
billing_address
Optional
Customer's billing address object. It contains attention, street, city, state, zip, country and fax.
attention
Optional
Attention of the customer's billing address.
street
Optional
Street of the customer’s billing address.
city
Optional
City of the customer’s billing address.
state
Optional
State of the customer’s billing address.
country
Optional
Country of the customer’s billing address.
zip
Optional
Zip code of the customer’s billing address.
fax
Optional
Fax number of the customer's billing address.
shipping_address
Optional
Customer's shipping address object. It contains attention, street, city, state, zip, country and fax.
attention
Optional
Attention of the customer’s shipping address.
street
Optional
Street of the customer’s shipping address.
city
Optional
City of the customer’s shipping address.
state
Optional
State of the customer’s shipping address.
country
Optional
Country of the customer’s shipping address.
zip
Optional
Zip code of the customer’s shipping address.
fax
Optional
Fax number of the customer’s shipping address.
payment_terms
Optional
Payment Due details for the invoices.
payment_terms_label
Optional
Label for the paymet due details.
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.
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.
tax_authority_name
Applicable for Sales Tax
Required
Unique name of the tax authority.
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.
default_templates
Optional
Default templates associated with the customer.
invoice_template_id
Optional
Unique Id used to denote the invoice template.
creditnote_template_id
Optional
Unique Id used to denote the credit note template.
place_of_contact
Applicable only for India GST
Required for non composite scheme indian GST registered organization
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, overseas
business_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.
contactpersons
Optional
List of contact person objects. Each object contains contactperson_id and email.
contactperson_id
Required
Contact person ID of the customer’s contact person.
Required
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.
quantity
Optional
Required quantity of the chosen plan.
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.
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.
Optional
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.
quantity
Optional
Required quantity of the chosen plan.
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.
reference_id
Optional
A string of your choice is required to easily identify and keep track of your subscriptions.
additional_param
Optional
Additional Params for the URL.
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.
custom_fields
Optional
Additional fields for the Hosted pages.
label
Optional
Label of the custom field.
value
Optional
Value of the custom field.
coupon_code
Optional
The coupon code of the coupon which is to be applied to the subscription.
redirect_url
Optional
It specifies the url to which the customer will be redirected after successful transaction.
salesperson_name
Optional
Name of tha sales person assigned for the subscription.

Update a subscription

Create a hosted page for a updating a subscription.

POST /hostedpages/updatesubscription

Request Example

  
$ curl https://subscriptions.zoho.com/api/v1/hostedpages/updatesubscription -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "X-com-zoho-subscriptions-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8" -d '{ "subscription_id": "9030000079200", "plan": { "plan_code": "basic-monthly", "plan_description": "Monthly Basic plan", "price": 20, "setup_fee": 20, "quantity": 1, "tax_id": "90300000023123", "tax_exemption_id": "903000006345", "tax_exemption_code": "GST FREE", "setup_fee_tax_exemption_id": "9030000123098", "setup_fee_tax_exemption_code": "GST FREE", "exclude_trial": false, "exclude_setup_fee": false, "billing_cycles": -1, "trial_days": 0 }, "addons": [ { "addon_code": "Email-basic", "addon_description": "Monthly addon.", "price": 20, "quantity": 1, "tax_id": "90300000023123", "tax_exemption_id": "903000006345", "tax_exemption_code": "GST FREE" } ], "auto_collect": true, "reference_id": "bowmanfurniture", "additional_param": "new_subscription", "starts_at": "2016-06-05", "custom_fields": [ { "label": "label", "value": "129890" } ], "coupon_code": "Flat10", "salesperson_name": "Franklin", "redirect_url": "http://www.zillum.com/products/piperhost" }

Response Example

  
HTTP/1.1 201 Created Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Hosted page has been created successfully.", "hostedpage": { "hostedpage_id": "8c589071e7e26a8d28e8af081c373fb00bd6dc5366fd129eefd5c61c569da526", "status": "success", "url": "https://subscriptions.zoho.com/hostedpage/8c589071e7e26a8d28e8af081c373fb00bd6dc5366fd129eefd5c61c569da526/checkout", "action": "new_subscription", "expiring_time": "2016-06-05T00:11:16-0700", "created_time": "2016-06-05T23:10:16-0700" } }

ARGUMENTS

subscription_id
Required
Unique ID generated for a subscription.
Required
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.
quantity
Optional
Required quantity of the chosen plan.
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.
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.
Optional
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.
quantity
Optional
Required quantity of the chosen plan.
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.
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.
additional_param
Optional
Additional Params for the URL.
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.
custom_fields
Optional
Additional fields for the Hosted pages.
label
Optional
Label of the custom field.
value
Optional
Value of the custom field.
coupon_code
Optional
The coupon code of the coupon which is to be applied to the subscription.
salesperson_name
Optional
Name of tha sales person assigned for the subscription.
redirect_url
Optional
It specifies the url to which the customer will be redirected after successful transaction.

Update card for a subscription

Create hosted page for updating card information for a subscription.

POST /hostedpages/updatecard

Request Example

  
$ curl https://subscriptions.zoho.com/api/v1/hostedpages/updatecard -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "X-com-zoho-subscriptions-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8" -d '{ "subscription_id": "9030000079200", "additional_param": "update_card", "auto_collect": true, "redirect_url": "http://www.zillum.com/products/piperhost" }

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Hosted page has been created successfully.", "hostedpage": { "hostedpage_id": "8c589071e7e26a8d28e8af081c373fb00bd6dc5366fd129eefd5c61c569da526", "status": "success", "url": "https://subscriptions.zoho.com/hostedpage/8c589071e7e26a8d28e8af081c373fb00bd6dc5366fd129eefd5c61c569da526/checkout", "action": "new_subscription", "expiring_time": "2016-06-05T00:11:16-0700", "created_time": "2016-06-05T23:10:16-0700" } }

ARGUMENTS

subscription_id
Required
Unique ID generated for a subscription.
additional_param
Optional
Additional Params for the URL.
auto_collect
Optional
auto_collect is set to true for charging customer's card automatically.
redirect_url
Optional
It specifies the url to which the customer will be redirected after successful transaction.

Buy one-time addon for a subscription

Create hosted page for buying a one-time addon for a subscription.

POST /hostedpages/buyonetimeaddon

Request Example

  
$ curl https://subscriptions.zoho.com/api/v1/hostedpages/buyonetimeaddon -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "X-com-zoho-subscriptions-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8" -d '{ "subscription_id": "9030000079200", "addons": [ { "addon_code": "Email-basic", "quantity": 1, "price": 20, "tax_id": "90300000023123", "tax_exemption_id": "903000006345", "tax_exemption_code": "GST FREE", "product_type": "goods" } ], "additional_param": "one_time_addon_purchase", "redirect_url": "http://www.zillum.com/products/piperhost" }

Response Example

  
HTTP/1.1 201 Created Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "Hosted page has been created successfully.", "hostedpage": { "hostedpage_id": "8c589071e7e26a8d28e8af081c373fb00bd6dc5366fd129eefd5c61c569da526", "status": "success", "url": "https://subscriptions.zoho.com/hostedpage/8c589071e7e26a8d28e8af081c373fb00bd6dc5366fd129eefd5c61c569da526/checkout", "action": "new_subscription", "expiring_time": "2016-06-05T00:11:16-0700", "created_time": "2016-06-05T23:10:16-0700", "custom_fields": [ { "index": 1, "value": "129890", "label": "label", "data_type": "string" } ] } }

ARGUMENTS

subscription_id
Required
Unique ID generated for a subscription.
Required
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.
quantity
Optional
Required quantity of the chosen plan.
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.
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.
additional_param
Optional
Additional Params for the URL.
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.

Example

{ "event_id": "90300000005337", "event_type": "subscription_activation", "event_time": "2016-06-05T18:28:20-0700", "payload": "{...}", "webhooks": [ { "webhook_id": "9030000020202", "url": "http://gatehost/webhooks/newsubscription/add", "status": "success", "last_updated_time": "2016-07-01T20:28:20-0700" } ] }

Attribute

event_id
string
Unique ID generated for a particular event
event_type
string
The type of event.
event_time
string
The time at which the event is created.
payload
string
Holds information about the event that occurred.
list
List of objects holds information about the webhooks. Each object contains webhook_id, url, status and last_updated_time.
webhook_id
string
The unique ID generated for a webhook by the server. This can be used as an identifier.
url
string
The URL for which the webhook is sent.
status
string
Status of the webhook. This can be success, scheduled or failure.
last_updated_time
string
The time at which the webhook was last sent.

Retrieve an event

Details of an existing event.

GET /events/{event_id}

Request Example

  
$ curl https://subscriptions.zoho.com/api/v1/events/{event_id} -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "X-com-zoho-subscriptions-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "event": { "event_id": "90300000005337", "event_type": "subscription_activation", "event_time": "2016-06-05T18:28:20-0700", "payload": "{...}", "webhooks": [ { "webhook_id": "9030000020202", "url": "http://gatehost/webhooks/newsubscription/add", "status": "success", "last_updated_time": "2016-07-01T20:28:20-0700" } ] } }

List of events

List of all events.

GET /events

Request Example

  
$ curl https://subscriptions.zoho.com/api/v1/events -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "X-com-zoho-subscriptions-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "events": [ { "event_id": "90300000005337", "event_type": "subscription_activation", "event_time": "2016-06-05T18:28:20-0700" }, {...}, {...} ] }

Event Types

The following are the list of events that Zoho Subscriptions currently supports.

Note: For backdated subscriptions, events will not be created for any actions that occur in a date previous than the current date.

Events

subscription_created
Triggered when a subscription is created
trial_expiring
Triggered 3 days before when a subscription trial is about to expire
subscription_activated
Triggered when a subscription gets to Live state
subscription_ahead
Triggered 3 days before a subscription is about to renew
subscription_renewed
Triggered when a subscription is renewed
billing_date_changed
Triggered when the billing date for a subscription is changed
subscription_upgraded
Triggered when a subscription plan is upgraded from a lower to a higher plan
subscription_downgraded
Triggered when a subscription plan is downgraded from a higher to a lower plan
subscription_unpaid
Triggered when a subscription is marked as unpaid.
subscription_cancelled
Triggers when a subscription is cancelled.
subscription_reactivated
Triggered when a subscription is reactivated from the cancelled state.
subscription_cancellation_scheduled
Triggers when a subscription is chose to cancel at the next renewal.
subscription_expiring
Triggered 3 days before a subscriptions is about expire
subscription_expired
Triggers when a subscription is expired
subscription_deleted
Triggers when a subscription is deleted
invoice_created
Triggers when an invoice is raised
creditnote_added
Triggers when a credit note is added
payment_thankyou
Triggers when a payment for an invoice is recieved
payment_refunded
Triggers when a payment is refunded
payment_declined
Triggers when a payment for an invoice fails
card_expired
Triggers when a customer card is expired
card_expiring
Triggered 15 days before a customer card expires
card_deleted
Triggered when a customer card is deleted

Settings

Tax Settings Related APIs.

Example

{ "tax_id": "903000002345", "tax_name": "GST", "tax_percentage": 15, "tax_type": "tax_group" }

Attribute

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.
tax_name
string
Name of the tax to which subscription is associated.
tax_percentage
string
Percentage of tax.
tax_type
string
Specifies whether the tax is Simple tax or Tax Group.

Retrieve list of taxes

Retreives the list of taxes along with thier details

GET /settings/taxes

Request Example

  
$ curl https://subscriptions.zoho.com/api/v1/settings/taxes -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "X-com-zoho-subscriptions-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "taxes": [ { "is_default_tax": true, "is_editable": true, "tax_authority_id": "903000006345", "tax_authority_name": "ATO", "tax_id": "903000002345", "tax_name": "GST", "tax_percentage": 15, "tax_type": "tax_group" }, {...}, {...} ] }

Retrieve list of tax Exemptions

Retreives the list of tax Exemptions.

GET /settings/taxexemptions

Request Example

  
$ curl https://subscriptions.zoho.com/api/v1/settings/taxexemptions -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "X-com-zoho-subscriptions-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "taxes": [ { "description": "Non-Profit Organization", "tax_exemption_id": "903000006345", "tax_exemption_code": "GST FREE", "type": "customer" }, {...}, {...} ] }

Retrieve list of tax Authorities

Retreives the list of tax Authorities

GET /settings/taxauthorities

Request Example

  
$ curl https://subscriptions.zoho.com/api/v1/settings/taxauthorities -H "Authorization: Zoho-authtoken ba4604e8e433g9c892e360d53463oec5" -H "X-com-zoho-subscriptions-organizationid: 10234695" -H "Content-Type: application/json;charset=UTF-8"

Response Example

  
HTTP/1.1 200 OK Content-Type:application/json;charset=UTF-8 { "code": 0, "message": "success", "taxes": [ { "description": "Non-Profit Organization", "tax_authority_id": "903000006345", "tax_authority_name": "ATO" }, {...}, {...} ] }