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
Used to uniquely identify the coupon in your website/application and to integrate with Chargebee.
string, max chars=50
The display name used in web interface for identifying the coupon.
string, max chars=50
Display name used in invoice. If it is not configured then name is used in invoice.
optional, string, max chars=100
The type of discount.
enumerated string, default=percentagePossible values are
fixed_amountThe specified amount will be given as discount.percentageThe specified percentage will be given as discount.
Discount value in percentage.
optional, double, min=0.01, max=100.0
Discount value in cents.
optional, in cents, min=0
Specifies the time duration this coupon is applicable.
enumerated string, default=foreverPossible values are
one_timeDiscount is applied once.foreverDiscount is applied for each billing cycle of the subscription.limited_periodDiscount is applied for the specified number of months.
The duration in months for the coupon to be applied. Applicable only to limited period coupon.
optional, integer, min=1, max=240
Date upto which the coupon can be applied to new subscriptions.
optional, timestamp(UTC) in seconds
Maximum number of times this coupon can be redeemed.
optional, integer, min=1
Status of the coupon.
optional, enumerated string, default=activePossible 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.
The invoice items for which this discounts need to be applied.
enumerated stringPossible values are
invoice_amountDiscount will be applied to the total invoice amount.each_specified_itemDiscount will be applied to each plan and addon item specified.
Plans the coupon can be applied to.
enumerated stringPossible 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.
Addons the coupon can be applied to.
enumerated stringPossible 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.
Timestamp indicating when this coupon is created.
timestamp(UTC) in seconds
Timestamp indicating when this coupon was archived.
optional, timestamp(UTC) in seconds
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, list of string
The number of times this coupon has been redeemed.
optional, integer, min=0
Invoice Notes for this resource.
optional, string, max chars=2000
A set of key-value pairs stored as additional information for the subscription.
Learn more.
optional, jsonobject
Create a new coupon.
Sample Request
curl https://{site}.chargebee.com/api/v1/coupons \
-u {site_api_key}:\
-d id="sample_offer" \
-d name="Sample Offer" \
-d discount_type="fixed_amount" \
-d discount_amount=500 \
-d apply_on="invoice_amount" \
-d duration_type="forever"
copy
curl https://{site}.chargebee.com/api/v1/coupons \
-u {site_api_key}:\
-d id="sample_offer" \
-d name="Sample Offer" \
-d discount_type="fixed_amount" \
-d discount_amount=500 \
-d apply_on="invoice_amount" \
-d duration_type="forever"
Sample Response [ 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
Used to uniquely identify the coupon in your website/application and to integrate with Chargebee.
required, string, max chars=50
The display name used in web interface for identifying the coupon.
required, string, max chars=50
Display name used in invoice. If it is not configured then name is used in invoice.
optional, string, max chars=100
The type of discount.
required, enumerated string, default=percentagePossible values are
fixed_amountThe specified amount will be given as discount.percentageThe specified percentage will be given as discount.
Discount value in cents.
optional, in cents, min=0
Discount value in percentage.
optional, double, min=0.01, max=100.0
The invoice items for which this discounts need to be applied.
required, enumerated stringPossible values are
invoice_amountDiscount will be applied to the total invoice amount.each_specified_itemDiscount will be applied to each plan and addon item specified.
Specifies the time duration this coupon is applicable.
required, enumerated string, default=foreverPossible values are
one_timeDiscount is applied once.foreverDiscount is applied for each billing cycle of the subscription.limited_periodDiscount is applied for the specified number of months.
The duration in months for the coupon to be applied. Applicable only to limited period coupon.
optional, integer, min=1, max=240
Date upto which the coupon can be applied to new subscriptions.
optional, timestamp(UTC) in seconds
Maximum number of times this coupon can be redeemed.
optional, integer, min=1
Invoice Notes for this resource.
optional, string, max chars=2000
A set of key-value pairs stored as additional information for the subscription.
Learn more.
optional, jsonobject
Plans the coupon can be applied to.
optional, enumerated stringPossible 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).
Addons the coupon can be applied to.
optional, enumerated stringPossible 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).
Identifier of the plan.
optional, list of string
Identifier of the addon.
optional, list of string
Resource object representing coupon.
always returned
List the available coupons.
Sample Request
curl https://{site}.chargebee.com/api/v1/coupons \
-G \
-u {site_api_key}:\
--data-urlencode limit=5
copy
curl https://{site}.chargebee.com/api/v1/coupons \
-G \
-u {site_api_key}:\
--data-urlencode limit=5
Sample Response [ 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
The number of resources to be returned.
optional, integer, default=10, min=1, max=100
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.
optional, string, max chars=1000
Resource object representing coupon.
always returned
next_offset
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”.
optional, string, max chars=1000
Retrieve a specific coupon using the id.
Sample Request
curl https://{site}.chargebee.com/api/v1/coupons/plan_only_coupon \
-u {site_api_key}:
copy
curl https://{site}.chargebee.com/api/v1/coupons/plan_only_coupon \
-u {site_api_key}:
Sample Response [ 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}
Resource object representing coupon.
always returned
Sample admin console URL
https://{site}.chargebee.com/admin-console/coupons/123x