API Docs
/
No Results Found
Coupons

Coupons

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

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, particular number of times or every time an invoice is raised for the subscription. It can either be one_time, duration, forever.
duration
integer
(Required) for duration type coupon.
This indicates the number of times the coupon has to applied to the invoices generated for a particular subscription.
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.
plans
array
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.
Show Sub-Attributes arrow
plan_code
string
The plan code of the plan to which the coupon is to be applied.
name
Plan to which the coupon is to be applied.
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.
addons
array
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.
Show Sub-Attributes arrow
addon_code
string
The addon code of the addon to which the coupon is to be applied.
name
Name of the coupon.
created_time
string
Time at which the coupon was created.
updated_time
string
Time at which the coupon details were last updated.

Example

{ "coupon_code": "THANKSGIVING20", "name": "Thanksgiving 20 percent offer", "description": "Twenty percent offer for thanks giving.", "type": "duration", "duration": 2, "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": "Basic" } ], "apply_to_addons": "select", "addons": [ { "addon_code": "Email-basic", "name": "Email Basic" } ], "created_time": "2016-06-05T18:02:26-0700", "updated_time": "2016-06-05T18:02:26-0700" }

Create an coupon

Create a new coupon.
oauthscope : ZohoSubscriptions.coupons.CREATE

Arguments

coupon_code
string
(Required)
Unique string of your choice which lets you identify this coupon.
name
string
(Required)
Name of the coupon to be displayed in the interface and invoices.
description
string
A small description about the coupon.
type
string
(Required)
This indicates whether the coupon is to be applied only once, particular number of times or every time an invoice is raised for the subscription. It can either be one_time, duration, forever.
duration
integer
(Required) for duration type coupon.
This indicates the number of times the coupon has to applied to the invoices generated for a particular subscription.
discount_by
string
(Required)
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
(Required)
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.
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.
plans
array
(Required) if apply_to_plans is selected
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.
Show Sub-Attributes arrow
plan_code
string
(Required)
The plan code of the plan to which the coupon is to be applied.
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.
addons
array
(Required) if apply_to_addons is selected
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.
Show Sub-Attributes arrow
addon_code
string
(Required)
The addon code of the addon to which the coupon is to be applied.

Request Example

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

Body Parameters

Click to copy
{ "coupon_code": "THANKSGIVING20", "name": "Thanksgiving 20 percent offer", "description": "Twenty percent offer for thanks giving.", "type": "duration", "duration": 2, "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

{ "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": "duration", "duration": 2, "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": "Basic" } ], "apply_to_addons": "select", "addons": [ { "addon_code": "Email-basic", "name": "Email Basic" } ], "created_time": "2016-06-05T18:02:26-0700", "updated_time": "2016-06-05T18:02:26-0700" } }

List all coupons

List of all coupons.
oauthscope : ZohoSubscriptions.coupons.READ

Query Parameters

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

Request Example

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

Response Example

{ "code": 0, "message": "success", "coupons": [ { "coupon_code": "THANKSGIVING20", "name": "Thanksgiving 20 percent offer", "description": "Twenty percent offer for thanks giving.", "type": "duration", "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" }, {...}, {...} ] }

Update a coupon

Update details of an existing coupon.
oauthscope : ZohoSubscriptions.coupons.UPDATE

Arguments

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

Request Example

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

Body Parameters

Click to copy
{ "name": "Thanksgiving 20 percent offer", "description": "Twenty percent offer for thanks giving.", "max_redemption": 50, "expiry_at": "2016-08-28" }

Response Example

{ "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": "duration", "duration": 2, "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": "Basic" } ], "apply_to_addons": "select", "addons": [ { "addon_code": "Email-basic", "name": "Email Basic" } ], "created_time": "2016-06-05T18:02:26-0700", "updated_time": "2016-06-05T18:02:26-0700" } }

Retrieve a coupon

Details of an existing coupon.
oauthscope : ZohoSubscriptions.coupons.READ

Request Example

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

Response Example

{ "code": 0, "message": "success", "coupon": { "coupon_code": "THANKSGIVING20", "name": "Thanksgiving 20 percent offer", "description": "Twenty percent offer for thanks giving.", "type": "duration", "duration": 2, "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": "Basic" } ], "apply_to_addons": "select", "addons": [ { "addon_code": "Email-basic", "name": "Email Basic" } ], "created_time": "2016-06-05T18:02:26-0700", "updated_time": "2016-06-05T18:02:26-0700" } }

Delete a coupon

Delete an existing coupon.
oauthscope : ZohoSubscriptions.coupons.DELETE

Request Example

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

Response Example

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

Mark as active

status of the coupon will be changed to active.
oauthscope : ZohoSubscriptions.coupons.CREATE

Request Example

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

Response Example

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

Mark as inactive

status of the coupon will be changed to inactive.
oauthscope : ZohoSubscriptions.coupons.CREATE

Request Example

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

Response Example

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