Coupons are discounts codes that you can configure and apply to subscriptions.
Sample coupon [ JSON ]
{
"addon_constraint": "not_applicable",
"apply_discount_on": "not_applicable",
"apply_on": "invoice_amount",
"created_at": 1517498159,
"currency_code": "USD",
"discount_amount": 500,
"discount_type": "fixed_amount",
"duration_type": "forever",
"id": "sample_offer",
"name": "Sample Offer",
"object": "coupon",
"plan_constraint": "not_applicable",
"redemptions": 0,
"resource_version": 1517498159000,
"status": "active",
"updated_at": 1517498159
}
API Index URL GET
https://{site}.chargebee.com/api/v1/coupons
Model Class
com.chargebee.models.Coupon
string, max chars=100 Used to uniquely identify the coupon in your website/application and to integrate with Chargebee.
Note:
When the coupon ID contains a special character; for example: #
, the API returns an error.
Make sure that you encode the coupon ID in the path parameter before making an API call.
string, max chars=50 The display name used in web interface for identifying the coupon.
Note:
When the name of the coupon set contains a special character; for example: #
, the API returns an error.
Make sure that you encode the name of the coupon set in the path parameter before making an API call.
optional, string, max chars=100 Display name used in invoice. If it is not configured then name is used in invoice.
enumerated string, default=percentage The type of deduction Possible values are
FIXED_AMOUNTThe specified amount will be deducted.PERCENTAGEThe specified percentage will be deducted.OFFER_QUANTITYApplies a discount based on the number of free units offered in a per unit plan subscription without reducing the total quantity sold.
FIXED_AMOUNTThe specified amount will be deducted.PERCENTAGEThe specified percentage will be deducted.OFFER_QUANTITYApplies a discount based on the number of free units offered in a per unit plan subscription without reducing the total quantity sold.
Show all values[+]
optional, double, min=0.01, max=100.0 The percentage of the original amount that should be deducted from it.
optional, in cents, min=0 The value of the deduction. The format of this value depends on the kind of currency.
optional, integer, min=1 Number of offered quantity for discount.
enumerated string, default=forever Specifies the time duration for which this coupon is attached to the subscription. Possible values are
ONE_TIMEThe coupon stays attached to the subscription till it is applied on an invoice once. It is removed after that from the subscription.FOREVERThe coupon is attached to the subscription and applied on the invoices until explicitly removed.LIMITED_PERIODThe discount is attached to the subscription and applied on the invoices for a limited duration. This duration starts from the point it is applied to an invoice for the first time and expires after a period specified by period
and period_unit
.
ONE_TIMEThe coupon stays attached to the subscription till it is applied on an invoice once. It is removed after that from the subscription.FOREVERThe coupon is attached to the subscription and applied on the invoices until explicitly removed.LIMITED_PERIODThe discount is attached to the subscription and applied on the invoices for a limited duration. This duration starts from the point it is applied to an invoice for the first time and expires after a period specified by period
and period_unit
.
Show all values[+]
optional, integer, min=1, max=240 (Deprecated) The duration of time in months for which the coupon is attached to the subscription. Applicable only when duration_type
is limited_period
.
Note: This parameter has been deprecated. Use period
and period_unit
instead.
optional, timestamp(UTC) in seconds Date upto which the coupon can be applied to new subscriptions.
optional, integer, min=1 Maximum number of times this coupon can be redeemed.
Note:
If not specified, the coupon can be redeemed an indefinite number of times.
optional, enumerated string, default=active Status of the coupon. Possible values are
ACTIVECan be applied to a subscription.EXPIREDCannot be applied to a subscription. A coupon may expire due to exceeding max_redemptions
or valid_till
date is past. Existing associations remain unaffected.ARCHIVEDCannot be applied to a subscription. Existing associations remain unaffected. ACTIVECan be applied to a subscription.EXPIREDCannot be applied to a subscription. A coupon may expire due to exceeding max_redemptions
or valid_till
date is past. Existing associations remain unaffected.ARCHIVEDCannot be applied to a subscription. Existing associations remain unaffected. Show all values[+]
enumerated string The amount on the invoice to which the coupon is applied. Possible values are
INVOICE_AMOUNTThe coupon is applied to the invoice sub_total
.EACH_SPECIFIED_ITEMThe coupon is applied to the invoice.line_item.amount
that corresponds to the plan or addon specified by plan_ids
and addon_ids
.
INVOICE_AMOUNTThe coupon is applied to the invoice sub_total
.EACH_SPECIFIED_ITEMThe coupon is applied to the invoice.line_item.amount
that corresponds to the plan or addon specified by plan_ids
and addon_ids
.
Show all values[+]
enumerated string Plans the coupon can be applied to. Possible values are
NONECoupon not applicable to any plans.ALLCoupon applicable to all plans.SPECIFICCoupon applicable to specific plan(s).NOT_APPLICABLECoupon only applicable to invoice amount and not any plans.
NONECoupon not applicable to any plans.ALLCoupon applicable to all plans.SPECIFICCoupon applicable to specific plan(s).NOT_APPLICABLECoupon only applicable to invoice amount and not any plans.
Show all values[+]
enumerated string Addons the coupon can be applied to. Possible values are
NONECoupon not applicable to any addons.ALLCoupon applicable to all addons.SPECIFICCoupon applicable to specific addon(s).NOT_APPLICABLECoupon only applicable to invoice amount and not any addons.
NONECoupon not applicable to any addons.ALLCoupon applicable to all addons.SPECIFICCoupon applicable to specific addon(s).NOT_APPLICABLECoupon only applicable to invoice amount and not any addons.
Show all values[+]
timestamp(UTC) in seconds Timestamp indicating when this coupon is created.
optional, timestamp(UTC) in seconds Timestamp indicating when this coupon was archived.
optional, list of string List of plan ids for which this coupon is applicable.
optional, list of string List of addon ids for which this coupon is applicable.
optional, integer, min=0 The number of times this coupon has been redeemed.
optional, string, max chars=2000 A customer-facing note added to all invoices associated with this API resource. This note becomes one among all the notes displayed on the invoice PDF.
optional, jsonobject A set of key-value pairs stored as additional information for the coupon. Learn more.
string, max chars=100 Used to uniquely identify the coupon in your website/application and to integrate with Chargebee.
Note:
When the coupon ID contains a special character; for example: #
, the API returns an error.
Make sure that you encode the coupon ID in the path parameter before making an API call.
string, max chars=50 The display name used in web interface for identifying the coupon.
Note:
When the name of the coupon set contains a special character; for example: #
, the API returns an error.
Make sure that you encode the name of the coupon set in the path parameter before making an API call.
optional, string, max chars=100 Display name used in invoice. If it is not configured then name is used in invoice.
enumerated string, default=percentage The type of deduction Possible values are
FIXED_AMOUNTThe specified amount will be deducted.PERCENTAGEThe specified percentage will be deducted.OFFER_QUANTITYApplies a discount based on the number of free units offered in a per unit plan subscription without reducing the total quantity sold.
FIXED_AMOUNTThe specified amount will be deducted.PERCENTAGEThe specified percentage will be deducted.OFFER_QUANTITYApplies a discount based on the number of free units offered in a per unit plan subscription without reducing the total quantity sold.
Show all values[+]
optional, double, min=0.01, max=100.0 The percentage of the original amount that should be deducted from it.
optional, in cents, min=0 The value of the deduction. The format of this value depends on the kind of currency.
optional, integer, min=1 Number of offered quantity for discount.
enumerated string, default=forever Specifies the time duration for which this coupon is attached to the subscription. Possible values are
ONE_TIMEThe coupon stays attached to the subscription till it is applied on an invoice once. It is removed after that from the subscription.FOREVERThe coupon is attached to the subscription and applied on the invoices until explicitly removed.LIMITED_PERIODThe discount is attached to the subscription and applied on the invoices for a limited duration. This duration starts from the point it is applied to an invoice for the first time and expires after a period specified by period
and period_unit
.
ONE_TIMEThe coupon stays attached to the subscription till it is applied on an invoice once. It is removed after that from the subscription.FOREVERThe coupon is attached to the subscription and applied on the invoices until explicitly removed.LIMITED_PERIODThe discount is attached to the subscription and applied on the invoices for a limited duration. This duration starts from the point it is applied to an invoice for the first time and expires after a period specified by period
and period_unit
.
Show all values[+]
optional, integer, min=1, max=240 (Deprecated) The duration of time in months for which the coupon is attached to the subscription. Applicable only when duration_type
is limited_period
.
Note: This parameter has been deprecated. Use period
and period_unit
instead.
optional, timestamp(UTC) in seconds Date upto which the coupon can be applied to new subscriptions.
optional, integer, min=1 Maximum number of times this coupon can be redeemed.
Note:
If not specified, the coupon can be redeemed an indefinite number of times.
optional, enumerated string, default=active Status of the coupon. Possible values are
ACTIVECan be applied to a subscription.EXPIREDCannot be applied to a subscription. A coupon may expire due to exceeding max_redemptions
or valid_till
date is past. Existing associations remain unaffected.ARCHIVEDCannot be applied to a subscription. Existing associations remain unaffected. ACTIVECan be applied to a subscription.EXPIREDCannot be applied to a subscription. A coupon may expire due to exceeding max_redemptions
or valid_till
date is past. Existing associations remain unaffected.ARCHIVEDCannot be applied to a subscription. Existing associations remain unaffected. Show all values[+]
enumerated string The amount on the invoice to which the coupon is applied. Possible values are
INVOICE_AMOUNTThe coupon is applied to the invoice sub_total
.EACH_SPECIFIED_ITEMThe coupon is applied to the invoice.line_item.amount
that corresponds to the plan or addon specified by plan_ids
and addon_ids
.
INVOICE_AMOUNTThe coupon is applied to the invoice sub_total
.EACH_SPECIFIED_ITEMThe coupon is applied to the invoice.line_item.amount
that corresponds to the plan or addon specified by plan_ids
and addon_ids
.
Show all values[+]
enumerated string Plans the coupon can be applied to. Possible values are
NONECoupon not applicable to any plans.ALLCoupon applicable to all plans.SPECIFICCoupon applicable to specific plan(s).NOT_APPLICABLECoupon only applicable to invoice amount and not any plans.
NONECoupon not applicable to any plans.ALLCoupon applicable to all plans.SPECIFICCoupon applicable to specific plan(s).NOT_APPLICABLECoupon only applicable to invoice amount and not any plans.
Show all values[+]
enumerated string Addons the coupon can be applied to. Possible values are
NONECoupon not applicable to any addons.ALLCoupon applicable to all addons.SPECIFICCoupon applicable to specific addon(s).NOT_APPLICABLECoupon only applicable to invoice amount and not any addons.
NONECoupon not applicable to any addons.ALLCoupon applicable to all addons.SPECIFICCoupon applicable to specific addon(s).NOT_APPLICABLECoupon only applicable to invoice amount and not any addons.
Show all values[+]
timestamp(UTC) in seconds Timestamp indicating when this coupon is created.
optional, timestamp(UTC) in seconds Timestamp indicating when this coupon was archived.
optional, list of string List of plan ids for which this coupon is applicable.
optional, list of string List of addon ids for which this coupon is applicable.
optional, integer, min=0 The number of times this coupon has been redeemed.
optional, string, max chars=2000 A customer-facing note added to all invoices associated with this API resource. This note becomes one among all the notes displayed on the invoice PDF.
optional, jsonobject A set of key-value pairs stored as additional information for the coupon. Learn more. This API creates a new coupon for a specific promotion or offers.
This API is not enabled for live sites by default. Please contact
support to get this enabled.
Sample Codes
import java.io.IOException;
import com.chargebee.*;
import com.chargebee.models.*;
import com.chargebee.models.enums.*;
public class Sample{
public static void main(String args[]) throws IOException{
Environment.configure("{site}","{site_api_key}");
Result result = Coupon.create()
.id("sample_offer")
.name("Sample Offer")
.discountType(DiscountType.FIXED_AMOUNT)
.discountAmount(500)
.applyOn(ApplyOn.INVOICE_AMOUNT)
.durationType(DurationType.FOREVER)
.request();
Coupon coupon = result.coupon();
System.out.println(result);
}
}
copy full code
Click to Copy
Environment.configure("{site}","{site_api_key}");
Result result = Coupon.create()
.id("sample_offer")
.name("Sample Offer")
.discountType(DiscountType.FIXED_AMOUNT)
.discountAmount(500)
.applyOn(ApplyOn.INVOICE_AMOUNT)
.durationType(DurationType.FOREVER)
.request();
Coupon coupon = result.coupon();
copy snippet
Click to Copy
Environment.configure("{site}","{site_api_key}");
Result result = Coupon.create()
.id("sample_offer")
.name("Sample Offer")
.discountType(DiscountType.FIXED_AMOUNT)
.discountAmount(500)
.applyOn(ApplyOn.INVOICE_AMOUNT)
.durationType(DurationType.FOREVER)
.request();
Coupon coupon = result.coupon();
Environment.configure("{site}","{site_api_key}");
Result result = Coupon.create()
.id("sample_offer")
.name("Sample Offer")
.discountType(DiscountType.FIXED_AMOUNT)
.discountAmount(500)
.applyOn(ApplyOn.INVOICE_AMOUNT)
.durationType(DurationType.FOREVER)
.request();
Coupon coupon = result.coupon();
Sample Result [ JSON ]
Show more...
{
"coupon": {
"addon_constraint": "not_applicable",
"apply_discount_on": "not_applicable",
"apply_on": "invoice_amount",
"created_at": 1517498159,
"currency_code": "USD",
"discount_amount": 500,
"discount_type": "fixed_amount",
"duration_type": "forever",
"id": "sample_offer",
"name": "Sample Offer",
"object": "coupon",
"plan_constraint": "not_applicable",
"redemptions": 0,
"resource_version": 1517498159000,
"status": "active",
"updated_at": 1517498159
}
}
URL Format
POST
https://{site}.chargebee.com/api/v1/coupons
required, string, max chars=100 Used to uniquely identify the coupon in your website/application and to integrate with Chargebee.
Note:
When the coupon ID contains a special character; for example: #
, the API returns an error.
Make sure that you encode the coupon ID in the path parameter before making an API call.
.
required, string, max chars=50 The display name used in web interface for identifying the coupon.
Note:
When the name of the coupon set contains a special character; for example: #
, the API returns an error.
Make sure that you encode the name of the coupon set in the path parameter before making an API call.
.
optional, string, max chars=100 Display name used in invoice. If it is not configured then name is used in invoice.
optional, enumerated string, default=percentage The type of deduction. Possible values are
FIXED_AMOUNTThe specified amount will be deducted.PERCENTAGEThe specified percentage will be deducted.OFFER_QUANTITYApplies a discount based on the number of free units offered in a per unit plan subscription without reducing the total quantity sold.
FIXED_AMOUNTThe specified amount will be deducted.PERCENTAGEThe specified percentage will be deducted.OFFER_QUANTITYApplies a discount based on the number of free units offered in a per unit plan subscription without reducing the total quantity sold.
Show all values[+] discountAmount[(val)](val)
optional, in cents, min=0 The value of the deduction. The format of this value depends on the kind of currency. discountPercentage[(val)](val)
optional, double, min=0.01, max=100.0 The percentage of the original amount that should be deducted from it. discountQuantity[(val)](val)
optional, integer, min=1 Number of offered quantity for discount.
required, enumerated string The amount on the invoice to which the coupon is applied. Possible values are
INVOICE_AMOUNTThe coupon is applied to the invoice sub_total
.EACH_SPECIFIED_ITEMThe coupon is applied to the invoice.line_item.amount
that corresponds to the plan or addon specified by plan_ids
and addon_ids
.
INVOICE_AMOUNTThe coupon is applied to the invoice sub_total
.EACH_SPECIFIED_ITEMThe coupon is applied to the invoice.line_item.amount
that corresponds to the plan or addon specified by plan_ids
and addon_ids
.
Show all values[+]
optional, enumerated string, default=forever Specifies the time duration for which this coupon is attached to the subscription. Possible values are
ONE_TIMEThe coupon stays attached to the subscription till it is applied on an invoice once. It is removed after that from the subscription.FOREVERThe coupon is attached to the subscription and applied on the invoices until explicitly removed.LIMITED_PERIODThe discount is attached to the subscription and applied on the invoices for a limited duration. This duration starts from the point it is applied to an invoice for the first time and expires after a period specified by period
and period_unit
.
ONE_TIMEThe coupon stays attached to the subscription till it is applied on an invoice once. It is removed after that from the subscription.FOREVERThe coupon is attached to the subscription and applied on the invoices until explicitly removed.LIMITED_PERIODThe discount is attached to the subscription and applied on the invoices for a limited duration. This duration starts from the point it is applied to an invoice for the first time and expires after a period specified by period
and period_unit
.
Show all values[+] durationMonth[(val)](val)
optional, integer, min=1, max=240 (Deprecated) The duration of time in months for which the coupon is attached to the subscription. Applicable only when duration_type
is limited_period
.
Note: This parameter has been deprecated. Use period
and period_unit
instead.
optional, timestamp(UTC) in seconds Date upto which the coupon can be applied to new subscriptions. maxRedemptions[(val)](val)
optional, integer, min=1 Maximum number of times this coupon can be redeemed.
Note:
If not specified, the coupon can be redeemed an indefinite number of times.
.
optional, string, max chars=2000 A customer-facing note added to all invoices associated with this API resource. This note becomes one among all the notes displayed on the invoice PDF.
optional, jsonobject A set of key-value pairs stored as additional information for the coupon. Learn more. planConstraint[(val)](val)
optional, enumerated string Plans the coupon can be applied to. Possible values are
NONECoupon not applicable to any plans.ALLCoupon applicable to all plans.SPECIFICCoupon only applicable to specified plans. If used, it is mandatory to specify the plan(s).
NONECoupon not applicable to any plans.ALLCoupon applicable to all plans.SPECIFICCoupon only applicable to specified plans. If used, it is mandatory to specify the plan(s).
Show all values[+] addonConstraint[(val)](val)
optional, enumerated string Addons the coupon can be applied to. Possible values are
NONECoupon not applicable to any addons.ALLCoupon applicable to all addons.SPECIFICCoupon only applicable to specified addons. If used, it is mandatory to specify the addon(s).
NONECoupon not applicable to any addons.ALLCoupon applicable to all addons.SPECIFICCoupon only applicable to specified addons. If used, it is mandatory to specify the addon(s).
Show all values[+]
optional, list of string Identifier of the plan.
optional, list of string Identifier of the addon.
always returned required
Resource object representing coupon
Sample admin console URL
https://{site}.chargebee.com/admin-console/coupons/123x
List all the available coupons that are created for a specific promotion or offers. You can find list of coupon codes that are currently active, expired, archived or deleted.
This API is not enabled for live sites by default. Please contact
support to get this enabled.
Sample Codes
import java.io.IOException;
import com.chargebee.*;
import com.chargebee.models.*;
import com.chargebee.models.enums.*;
public class Sample{
public static void main(String args[]) throws IOException{
Environment.configure("{site}","{site_api_key}");
ListResult result = Coupon.list()
.limit(5)
.request();
for(ListResult.Entry entry:result) {
Coupon coupon = entry.coupon();
}
System.out.println(result);
}
}
copy full code
Click to Copy
Environment.configure("{site}","{site_api_key}");
ListResult result = Coupon.list()
.limit(5)
.request();
for(ListResult.Entry entry:result) {
Coupon coupon = entry.coupon();
}
copy snippet
Click to Copy
Environment.configure("{site}","{site_api_key}");
ListResult result = Coupon.list()
.limit(5)
.request();
for(ListResult.Entry entry:result) {
Coupon coupon = entry.coupon();
}
Environment.configure("{site}","{site_api_key}");
ListResult result = Coupon.list()
.limit(5)
.request();
for(ListResult.Entry entry:result) {
Coupon coupon = entry.coupon();
}
Sample Result [ JSON ]
Show more...
{
"list": [
{
"coupon": {
"addon_constraint": "none",
"apply_discount_on": "not_applicable",
"apply_on": "each_unit_of_specified_items",
"created_at": 1552317358,
"discount_amount": 200,
"discount_type": "fixed_amount",
"duration_type": "forever",
"id": "plan_quantity_coupon",
"name": "Plan Quantity Coupon",
"object": "coupon",
"plan_constraint": "all",
"redemptions": 0,
"status": "active"
}
},
{..}
],
"next_offset": "[\"1517498159000\",\"135000000555\"]"
}
URL Format
GET
https://{site}.chargebee.com/api/v1/coupons
optional, integer, default=10, min=1, max=100 The number of resources to be returned.
optional, string, max chars=1000 Determines your position in the list for pagination. To ensure that the next page is retrieved correctly, always set offset
to the value of next_offset
obtained in the previous iteration of the API call.
always returned required
Resource object representing coupon
always returned optional, string, max chars=1000
This attribute is returned only if more resources are present. To fetch the next set of resources use this value for the input parameter `offset`.
Sample admin console URL
https://{site}.chargebee.com/admin-console/coupons/123x
This API retrieves a specific coupon using the coupon ID.
This API is not enabled for live sites by default. Please contact
support to get this enabled.
Sample Codes
import java.io.IOException;
import com.chargebee.*;
import com.chargebee.models.*;
import com.chargebee.models.enums.*;
public class Sample{
public static void main(String args[]) throws IOException{
Environment.configure("{site}","{site_api_key}");
Result result = Coupon.retrieve("plan_only_coupon").request();
Coupon coupon = result.coupon();
System.out.println(result);
}
}
copy full code
Click to Copy
Environment.configure("{site}","{site_api_key}");
Result result = Coupon.retrieve("plan_only_coupon").request();
Coupon coupon = result.coupon();
copy snippet
Click to Copy
Environment.configure("{site}","{site_api_key}");
Result result = Coupon.retrieve("plan_only_coupon").request();
Coupon coupon = result.coupon();
Environment.configure("{site}","{site_api_key}");
Result result = Coupon.retrieve("plan_only_coupon").request();
Coupon coupon = result.coupon();
Sample Result [ JSON ]
Show more...
{
"coupon": {
"addon_constraint": "none",
"apply_discount_on": "not_applicable",
"apply_on": "each_specified_item",
"created_at": 1552317358,
"discount_percentage": 10,
"discount_type": "percentage",
"duration_type": "forever",
"id": "plan_only_coupon",
"name": "Plan Only Coupon",
"object": "coupon",
"plan_constraint": "all",
"redemptions": 0,
"status": "active"
}
}
URL Format
GET
https://{site}.chargebee.com/api/v1/coupons/{coupon-id}
Method
Coupon.retrieve(<coupon_id>)
always returned required
Resource object representing coupon
Sample admin console URL
https://{site}.chargebee.com/admin-console/coupons/123x