Coupons are deductions applied to invoices or invoice line items. They’re designed to be consumed by your customers directly. A coupon deduction can either be for a fixed amount or for a percentage of the amount of the invoice or line item.

Sample coupon [ JSON ]

{ "addon_constraint": "not_applicable", "apply_discount_on": "not_applicable", "apply_on": "invoice_amount", "created_at": 1517505786, "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": 1517505786000, "status": "active", "updated_at": 1517505786 }

API Index URL GET

https://{site}.chargebee.com/api/v2/coupons
id
Used to uniquely identify the coupon in your website/application and to integrate with Chargebee.
string, max chars=100
name
The display name used in web interface for identifying the coupon.
string, max chars=50
invoice_name
Display name used in invoice. If it is not configured then name is used in invoice.
optional, string, max chars=100
discount_type
The type of deduction.
enumerated string, default=percentage
Possible values are
fixed_amountThe specified amount will be deducted.percentageThe specified percentage will be deducted.
discount_percentage
The percentage of the original amount that should be deducted from it.
optional, double, min=0.01, max=100.0
discount_amount
The value of the deduction. The format of this value depends on the kind of currency.
optional, in cents, min=0
currency_code
The currency code (ISO 4217 format) of the coupon. Applicable for fixed_amount coupons alone.
optional, string, max chars=3
duration_type
Specifies the time duration for which this coupon is attached to the subscription.
enumerated string, default=forever
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. .
valid_till
Date upto which the coupon can be applied to new subscriptions.
optional, timestamp(UTC) in seconds
max_redemptions

Maximum number of times this coupon can be redeemed.

Note:

If not specified, the coupon can be redeemed an indefinite number of times.

.
optional, integer, min=1
status
Status of the coupon.
optional, enumerated string, default=active
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.deletedIndicates the coupon has been deleted.
apply_on
The amount on the invoice to which the coupon is applied.
enumerated string
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.
plan_constraint
Plans the coupon can be applied to.
enumerated string
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.
addon_constraint
Addons the coupon can be applied to.
enumerated string
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.
created_at
Timestamp indicating when this coupon is created.
timestamp(UTC) in seconds
archived_at
Timestamp indicating when this coupon was archived.
optional, timestamp(UTC) in seconds
resource_version
Version number of this resource. Each update of this resource results in incremental change of this number.
optional, long
updated_at
Timestamp indicating when this coupon was last updated. Note that this does not change when the 'redemptions' attribute is changed. This attribute will be present only if the resource has been updated after 2016-11-09.
optional, timestamp(UTC) in seconds
included_in_mrr
The coupon is included in MRR calculations for your site. This attribute is only applicable for coupons of duration_type = one_time and when the feature is enabled in Chargebee. Note: If the site-level setting is to exclude one-time coupons from MRR calculations, this value is always returned false.
optional, boolean
period
The duration of time for which the coupon is attached to the subscription, in period_units. Applicable only when duration_type is limited_period.
optional, integer, min=1
period_unit
The unit of time for period. Applicable only when duration_type is limited_period.
optional, enumerated string
Possible values are
dayA period of 24 hours.weekA period of 7 days.monthA period of 1 calendar month.yearA period of 1 calendar year.
plan_ids
List of plan ids for which this coupon is applicable.
optional, list of string
addon_ids
List of addon ids for which this coupon is applicable.
optional, list of string
redemptions
The number of times this coupon has been redeemed.
optional, integer, min=0
invoice_notes
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, string, max chars=2000
meta_data
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/v2/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/v2/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": 1517505786, "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": 1517505786000, "status": "active", "updated_at": 1517505786 }}

URL Format POST

https://{site}.chargebee.com/api/v2/coupons
id
Used to uniquely identify the coupon in your website/application and to integrate with Chargebee.
required, string, max chars=100
name
The display name used in web interface for identifying the coupon.
required, string, max chars=50
invoice_name
Display name used in invoice. If it is not configured then name is used in invoice.
optional, string, max chars=100
discount_type
The type of deduction.
required, enumerated string, default=percentage
Possible values are
fixed_amountThe specified amount will be deducted.percentageThe specified percentage will be deducted.
discount_amount
The value of the deduction. The format of this value depends on the kind of currency.
optional, in cents, min=0
currency_code
The currency code (ISO 4217 format) of the coupon. Applicable for fixed_amount coupons alone.
required if Multicurrency is enabled, string, max chars=3
discount_percentage
The percentage of the original amount that should be deducted from it.
optional, double, min=0.01, max=100.0
apply_on
The amount on the invoice to which the coupon is applied.
required, enumerated string
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.
duration_type
Specifies the time duration for which this coupon is attached to the subscription.
required, enumerated string, default=forever
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. .
duration_month
(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, integer, min=1, max=240
valid_till
Date upto which the coupon can be applied to new subscriptions.
optional, timestamp(UTC) in seconds
max_redemptions

Maximum number of times this coupon can be redeemed.

Note:

If not specified, the coupon can be redeemed an indefinite number of times.

.
optional, integer, min=1
invoice_notes
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, string, max chars=2000
meta_data
A set of key-value pairs stored as additional information for the subscription. Learn more.
optional, jsonobject
included_in_mrr
The coupon is included in MRR calculations for your site. This attribute is only applicable for coupons of duration_type = one_time and when the feature is enabled in Chargebee. Note: If the site-level setting is to exclude one-time coupons from MRR calculations, this value is always returned false.
optional, boolean
period
The duration of time for which the coupon is attached to the subscription, in period_units. Applicable only when duration_type is limited_period.
optional, integer, min=1
period_unit
The unit of time for period. Applicable only when duration_type is limited_period.
optional, enumerated string
Possible values are
dayA period of 24 hours.weekA period of 7 days.monthA period of 1 calendar month.yearA period of 1 calendar year.
plan_constraint
Plans the coupon can be applied to.
optional, enumerated string
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).
addon_constraint
Addons the coupon can be applied to.
optional, enumerated string
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).
plan_ids[0..n]
Identifier of the plan.
optional, list of string
addon_ids[0..n]
Identifier of the addon.
optional, list of string
status
Status of the coupon.
optional, enumerated string, default=active
Possible values are
activeCan be applied to a subscription.archivedCannot be applied to a subscription. Existing associations remain unaffected.
Resource object representing coupon.
always returned
List the available coupons.
Sample Request
curl  https://{site}.chargebee.com/api/v2/coupons \
     -G  \
     -u {site_api_key}:\
     --data-urlencode limit=5 \
     --data-urlencode duration_type[is]="forever" \
     --data-urlencode status[is]="active" \
     --data-urlencode sort_by[asc]="created_at"
copy
curl  https://{site}.chargebee.com/api/v2/coupons \
     -G  \
     -u {site_api_key}:\
     --data-urlencode limit=5 \
     --data-urlencode duration_type[is]="forever" \
     --data-urlencode status[is]="active" \
     --data-urlencode sort_by[asc]="created_at"

Sample Response [ JSON ]

Show more...
{"list": [ {"coupon": { "addon_constraint": "not_applicable", "apply_discount_on": "not_applicable", "apply_on": "invoice_amount", "created_at": 1517505786, "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": 1517505786000, "status": "active", "updated_at": 1517505786 }}, {..} ]}

URL Format GET

https://{site}.chargebee.com/api/v2/coupons
limit
The number of resources to be returned.
optional, integer, default=10, min=1, max=100
offset
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
sort_by[<sort-order>]
Sorts based on the specified attribute.
Supported attributes : created_at
Supported sort-orders : asc, desc

Example sort_by[asc] = "created_at"
This will sort the result based on the 'created_at' attribute in ascending(earliest first) order.
optional, string filter
Filter Params
For operator usages, see the Pagination and Filtering section.
id[<operator>]
Used to uniquely identify the coupon in your website/application and to integrate with Chargebee.
Supported operators : is, is_not, starts_with, in, not_in

Example id[is] = "OFF2008"
optional, string filter
name[<operator>]
The display name used in web interface for identifying the coupon.
Supported operators : is, is_not, starts_with, in, not_in

Example name[is] = "Offer 10"
optional, string filter
discount_type[<operator>]
The type of deduction. Possible values are : fixed_amount, percentage.
Supported operators : is, is_not, in, not_in

Example discount_type[is] = "fixed_amount"
optional, enumerated string filter
duration_type[<operator>]
Specifies the time duration for which this coupon is attached to the subscription. Possible values are : one_time, forever, limited_period.
Supported operators : is, is_not, in, not_in

Example duration_type[is] = "forever"
optional, enumerated string filter
status[<operator>]
Status of the coupon. Possible values are : active, expired, archived, deleted.
Supported operators : is, is_not, in, not_in

Example status[is] = "active"
optional, enumerated string filter
apply_on[<operator>]
The amount on the invoice to which the coupon is applied. Possible values are : invoice_amount, each_specified_item.
Supported operators : is, is_not, in, not_in

Example apply_on[is_not] = "invoice_amount"
optional, enumerated string filter
created_at[<operator>]
Timestamp indicating when this coupon is created.
Supported operators : after, before, on, between

Example created_at[before] = "145222875"
optional, timestamp(UTC) in seconds filter
updated_at[<operator>]
To filter based on updated at. This attribute will be present only if the resource has been updated after 2016-11-09.
Supported operators : after, before, on, between

Example updated_at[before] = "1243545465"
optional, timestamp(UTC) in seconds filter
currency_code[<operator>]
The currency code (ISO 4217 format) of the coupon. Applicable for fixed_amount coupons alone.
Supported operators : is, is_not, starts_with, in, not_in

Example currency_code[is] = "USD"
optional, string filter
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/v2/coupons/plan_only_coupon \
     -u {site_api_key}:
copy
curl  https://{site}.chargebee.com/api/v2/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": 1595179384, "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/v2/coupons/{coupon_id}
Resource object representing coupon.
always returned

Sample admin console URL

https://{site}.chargebee.com/admin-console/coupons/123x

When updating coupons that are already linked to an invoice or subscription you can only update the following parameters:

  • name
  • invoice name
  • plan_constraint - Applicable when apply_on is set as each_specified_item. Allows change from none to all, none to specific, and specific to all.
  • addon_constraint - Applicable when apply_on is set as each_specified_item. Allows change from none to all, none to specific, and specific to all.
  • plan_ids - Applicable when plan_constraint is set as specific. Allows addition of new plan_ids. However, existing plan_ids cannot be removed.
  • addon_ids - Applicable when addon_constraint is set as specific. Allows addition of new addon_ids. However, existing addon_ids cannot be removed.
  • valid_till
  • max_redemptions
  • invoice_notes
  • included_in_mrr
  • meta_data
Sample Request
curl  https://{site}.chargebee.com/api/v2/coupons/welcome_offer \
     -u {site_api_key}:\
     -d discount_type="percentage" \
     -d discount_percentage=10.0 \
     -d apply_on="invoice_amount" \
     -d duration_type="one_time"
copy
curl  https://{site}.chargebee.com/api/v2/coupons/welcome_offer \
     -u {site_api_key}:\
     -d discount_type="percentage" \
     -d discount_percentage=10.0 \
     -d apply_on="invoice_amount" \
     -d duration_type="one_time"

Sample Response [ JSON ]

Show more...
{"coupon": { "addon_constraint": "not_applicable", "apply_discount_on": "not_applicable", "apply_on": "invoice_amount", "created_at": 1517505791, "discount_percentage": 10, "discount_type": "percentage", "duration_type": "one_time", "id": "welcome_offer", "name": "welcome Offer", "object": "coupon", "plan_constraint": "not_applicable", "redemptions": 0, "resource_version": 1517505791000, "status": "active", "updated_at": 1517505791 }}

URL Format POST

https://{site}.chargebee.com/api/v2/coupons/{coupon_id}
name
The display name used in web interface for identifying the coupon.
optional, string, max chars=50
invoice_name
Display name used in invoice. If it is not configured then name is used in invoice.
optional, string, max chars=100
discount_type
The type of deduction.
optional, enumerated string
Possible values are
fixed_amountThe specified amount will be deducted.percentageThe specified percentage will be deducted.
discount_amount
The value of the deduction. The format of this value depends on the kind of currency.
optional, in cents, min=0
currency_code
The currency code (ISO 4217 format) of the coupon. Applicable for fixed_amount coupons alone.
required if Multicurrency is enabled, string, max chars=3
discount_percentage
The percentage of the original amount that should be deducted from it.
optional, double, min=0.01, max=100.0
apply_on
The amount on the invoice to which the coupon is applied.
optional, enumerated string
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.
duration_type
Specifies the time duration for which this coupon is attached to the subscription.
optional, enumerated string
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. .
duration_month
(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, integer, min=1, max=240
valid_till
Date upto which the coupon can be applied to new subscriptions.
optional, timestamp(UTC) in seconds
max_redemptions

Maximum number of times this coupon can be redeemed.

Note:

If not specified, the coupon can be redeemed an indefinite number of times.

.
optional, integer, min=1
invoice_notes
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, string, max chars=2000
meta_data
A set of key-value pairs stored as additional information for the subscription. Learn more.
optional, jsonobject
included_in_mrr
The coupon is included in MRR calculations for your site. This attribute is only applicable for coupons of duration_type = one_time and when the feature is enabled in Chargebee. Note: If the site-level setting is to exclude one-time coupons from MRR calculations, this value is always returned false.
optional, boolean
period
The duration of time for which the coupon is attached to the subscription, in period_units. Applicable only when duration_type is limited_period.
optional, integer, min=1
period_unit
The unit of time for period. Applicable only when duration_type is limited_period.
optional, enumerated string
Possible values are
dayA period of 24 hours.weekA period of 7 days.monthA period of 1 calendar month.yearA period of 1 calendar year.
plan_constraint
Plans the coupon can be applied to.
optional, enumerated string
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).
addon_constraint
Addons the coupon can be applied to.
optional, enumerated string
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).
plan_ids[0..n]
Identifier of the plan.
optional, list of string
addon_ids[0..n]
Identifier of the addon.
optional, list of string
Resource object representing coupon.
always returned

If no Subscriptions/Invoices are linked to this Coupon, the Coupon will be deleted from your Chargebee site. This action cannot be undone.

To ensure that existing Subscriptions/Invoices are not affected, Coupons associated with them will not be deleted, but moved to "Archived" state. Once a Coupon has been archived, it cannot be edited or used again unless unarchived. Unused Coupons codes are deleted.

Sample Request
curl  https://{site}.chargebee.com/api/v2/coupons/beta/delete \
     -X POST  \
     -u {site_api_key}:
copy
curl  https://{site}.chargebee.com/api/v2/coupons/beta/delete \
     -X POST  \
     -u {site_api_key}:

Sample Response [ JSON ]

Show more...
{"coupon": { "addon_constraint": "not_applicable", "apply_discount_on": "not_applicable", "apply_on": "invoice_amount", "created_at": 1517505787, "currency_code": "USD", "discount_amount": 500, "discount_type": "fixed_amount", "duration_type": "forever", "id": "beta", "name": "Beta", "object": "coupon", "plan_constraint": "not_applicable", "redemptions": 0, "resource_version": 1600968187440, "status": "deleted", "updated_at": 1600968187 }}

URL Format POST

https://{site}.chargebee.com/api/v2/coupons/{coupon_id}/delete
Resource object representing coupon.
always returned

Creates a coupon in this site by copying its configurations from another site. Copying of archived coupons is not supported.

Note:
  • The plans and addons (refer plan_constraint, plan_ids, addon_constraint, addon_ids) that are linked will also be copied. E.g. in the source site, the coupon C1 has P1 and P2 as applicable plans. Now, if in the destination site only the plan P1 is present, the newly created coupon will have only P1 as the applicable plan. So we recommend that you copy the necessary plans and addons before copying the coupons.
  • The 'redemptions' count is not copied. It will be 0 for the newly created coupon. Hence, if you are copying a Expired coupon (expired because max_redemptions is reached), its status will be 'Active' when created.
This API is not enabled for live sites by default. Please contact support@chargebee.com to get this enabled.
Sample Request
curl  https://{site}.chargebee.com/api/v2/coupons/copy \
     -u {site_api_key}:\
     -d from_site="merchant-test" \
     -d id_at_from_site="copy_coupon"
copy
curl  https://{site}.chargebee.com/api/v2/coupons/copy \
     -u {site_api_key}:\
     -d from_site="merchant-test" \
     -d id_at_from_site="copy_coupon"

Sample Response [ JSON ]

Show more...
{"coupon": { "addon_constraint": "not_applicable", "apply_discount_on": "not_applicable", "apply_on": "invoice_amount", "created_at": 1517505785, "currency_code": "USD", "discount_amount": 100, "discount_type": "fixed_amount", "duration_type": "one_time", "id": "copy_coupon", "name": "Copy Coupon", "object": "coupon", "plan_constraint": "not_applicable", "redemptions": 0, "resource_version": 1517505785000, "status": "active", "updated_at": 1517505785 }}

URL Format POST

https://{site}.chargebee.com/api/v2/coupons/copy
from_site
Your Chargebee site name having the coupon to be copied.
Note: Unless you are copying from a twin site (acme & acme-test are twin sites), please contact support@chargebee.com to have this white-listed.
required, string, max chars=50
id_at_from_site
Id of the coupon to be copied. The new coupon created in this site will have the same Id.
required, string, max chars=100
id
Id of copied coupon in this site.
optional, string, max chars=100
for_site_merging
If copy action is performed as part of Chargebee site merge action, pass the value as true.
Note: If this parameter is passed true coupon state, redmeptions, coupon set and coupon codes associated with this coupon will be copied.
optional, boolean, default=false
Resource object representing coupon.
always returned
Unarchives a specific coupon using the id.
Sample Request
curl  https://{site}.chargebee.com/api/v2/coupons/winter_offer/unarchive \
     -X POST  \
     -u {site_api_key}:
copy
curl  https://{site}.chargebee.com/api/v2/coupons/winter_offer/unarchive \
     -X POST  \
     -u {site_api_key}:

Sample Response [ JSON ]

Show more...
{"coupon": { "addon_constraint": "not_applicable", "apply_discount_on": "not_applicable", "apply_on": "invoice_amount", "created_at": 1517505790, "currency_code": "USD", "discount_amount": 500, "discount_type": "fixed_amount", "duration_type": "forever", "id": "winter_offer", "name": "Winter Offer", "object": "coupon", "plan_constraint": "not_applicable", "redemptions": 1, "resource_version": 1517505790000, "status": "active", "updated_at": 1517505790 }}

URL Format POST

https://{site}.chargebee.com/api/v2/coupons/{coupon_id}/unarchive
Resource object representing coupon.
always returned