You are viewing the documentation for Chargebee API V2. If you're using the older version (V1), click here.

Overview

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.

Note:

If you wish to provide discounts to your customers via API or the Chargebee app, see Discounts API

Order of application of coupons and discounts

When both coupons and discounts are applied simultaneously to a subscription or one-time invoice, they’re applied in the following order:

Summary

Description

1

Line-level, fixed amount coupons

coupon with apply_on = each_specified_item and discount_type = flat

2

Line-level, fixed amount discounts

discount with apply_on = specific_item_price and type = fixed_amount

3

Line-level, percentage coupons

coupon with apply_on = each_specified_item and discount_type = percentage

4

Line-level, percentage discounts

discount with apply_on = specific_item_price and type = percentage

5

Invoice-level, fixed amount coupons

coupon with apply_on = invoice_amount and discount_type = flat

6

Invoice-level, fixed amount discounts

discount with apply_on = invoice_amount and type = fixed_amount

7

Invoice-level, percentage coupons

coupon with apply_on = invoice_amount and discount_type = percentage

8

Invoice-level, percentage discounts

discount with apply_on = invoice_amount and type = percentage


For example, consider the following scenario:

A subscription is created with:

  • a plan price of $200 per month
  • an addon price of $20 per month
  • a flat $5 invoice discount
  • a 1% off coupon on the addon
  • a flat $2 coupon on the invoice

The above coupons and discount are applied in the following order:

Discount or coupon applied

Subtotal at each step

1

Initial subtotal (plan price + addon price)

$200 + $20 = $220

2

1% off coupon on the addon

$200 + $(20 - 0.02) = $200 + $19.98 = $219.98

3

Flat $2 coupon on the invoice

$219.98 - $2 = $217.98

4

Flat $5 invoice discount

$217.98 - $5 = $212.98

Sample coupon [ JSON ]

{ "apply_discount_on": "not_applicable", "apply_on": "each_specified_item", "created_at": 1517495314, "discount_percentage": 10, "discount_type": "percentage", "duration_type": "forever", "id": "summer_offer", "item_constraints": [ { "constraint": "all", "item_type": "plan" }, { "constraint": "none", "item_type": "addon" }, { "constraint": "none", "item_type": "charge" } ], "name": "Summer Offer", "object": "coupon", "redemptions": 0, "resource_version": 1517495314967, "status": "active", "updated_at": 1517495314 }

API Index URL GET

https://{site}.chargebee.com/api/v2/coupons
id
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.

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

.
invoice_name
optional, string, max chars=100
Display name used in invoice. If it is not configured then name is used in invoice.
discount_type
enumerated string, default=percentage
The type of deduction.
Possible values are
fixed_amountThe specified amount will be deducted.percentageThe specified percentage will be deducted.
discount_percentage
optional, double, min=0.01, max=100.0
The percentage of the original amount that should be deducted from it.
discount_amount
optional, in cents, min=0
The value of the deduction. The format of this value depends on the kind of currency.
currency_code
optional, string, max chars=3
The currency code (ISO 4217 format) of the coupon. Applicable for fixed_amount coupons alone.
duration_type
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. .
valid_till
optional, timestamp(UTC) in seconds
Date upto which the coupon can be applied to new subscriptions.
max_redemptions
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.

.
status
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.deletedIndicates the coupon has been deleted.
apply_on
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 item price specified by item_price_id.
created_at
timestamp(UTC) in seconds
Timestamp indicating when this coupon is created.
archived_at
optional, timestamp(UTC) in seconds
Timestamp indicating when this coupon was archived.
resource_version
optional, long
The version number of this resource. For every change made to the resource, resource_version is updated with a new timestamp in milliseconds.
updated_at
optional, timestamp(UTC) in seconds
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.
period
optional, integer, min=1
The duration of time for which the coupon is attached to the subscription, in period_units. Applicable only when duration_type is limited_period.
period_unit
optional, enumerated string
The unit of time for period. Applicable only when duration_type is limited_period.
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.
redemptions
optional, integer, min=0
The number of times this coupon has been redeemed.
invoice_notes
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.
item_constraints
Show attributes[+]
optional, list of item_constraint
The list of item constraints.
Item constraint attributes
item_type
enumerated string
Item type for which this criteria is applicable for.
Possible values are
planPlan.addonAddon.chargeCharge.
constraint
enumerated string
Constraint applicable for the item.
Possible values are
noneCoupon not applicable to any items.allCoupon applicable to all items.specificCoupon applicable to specific items.criteriaCoupon applicable based on criteria.
item_price_ids
optional, jsonarray
List of item price ids for which this coupon is applicable.
item_constraint_criteria
Show attributes[+]
optional, list of item_constraint_criteria
The list of item constraint criteria.
Item constraint criteria attributes
item_type
enumerated string
Item type for which this criteria is applicable for.
Possible values are
planPlan is a type of item.addonAddon is a type of item.chargeCharge is a type of item.
currencies
optional, jsonarray
List of currencies (ISO 4217 format) for which this coupon is applicable.
item_family_ids
optional, jsonarray
List of families for which this coupon is applicable.
item_price_periods
optional, jsonarray
List of frequencies for which this coupon is applicable. Allowed frequencies are [day, week, month, year].
This API creates a new coupon for a specific promotion or offers.
Sample Request
curl  https://{site}.chargebee.com/api/v2/coupons/create_for_items \
     -u {site_api_key}:\
     -d id="summer_offer" \
     -d name="Summer Offer" \
     -d discount_percentage=10.0 \
     -d discount_type="percentage" \
     -d duration_type="forever" \
     -d apply_on="each_specified_item" \
     -d item_constraints[constraint][0]="all" \
     -d item_constraints[item_type][0]="plan"
copy
curl  https://{site}.chargebee.com/api/v2/coupons/create_for_items \
     -u {site_api_key}:\
     -d id="summer_offer" \
     -d name="Summer Offer" \
     -d discount_percentage=10.0 \
     -d discount_type="percentage" \
     -d duration_type="forever" \
     -d apply_on="each_specified_item" \
     -d item_constraints[constraint][0]="all" \
     -d item_constraints[item_type][0]="plan"

Sample Response [ JSON ]

Show more...
{"coupon": { "apply_discount_on": "not_applicable", "apply_on": "each_specified_item", "created_at": 1517495314, "discount_percentage": 10, "discount_type": "percentage", "duration_type": "forever", "id": "summer_offer", "item_constraints": [ { "constraint": "all", "item_type": "plan" }, {..} ], "name": "Summer Offer", "object": "coupon", "redemptions": 0, "resource_version": 1517495314967, "status": "active", "updated_at": 1517495314 }}

URL Format POST

https://{site}.chargebee.com/api/v2/coupons/create_for_items
id
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.

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

.
invoice_name
optional, string, max chars=100
Display name used in invoice. If it is not configured then name is used in invoice.
discount_type
required, enumerated string, default=percentage
The type of deduction.
Possible values are
fixed_amountThe specified amount will be deducted.percentageThe specified percentage will be deducted.
discount_amount
optional, in cents, min=0
The value of the deduction. The format of this value depends on the kind of currency.
currency_code
required if Multicurrency is enabled, string, max chars=3
The currency code (ISO 4217 format) of the coupon. Applicable for fixed_amount coupons alone.
discount_percentage
optional, double, min=0.01, max=100.0
The percentage of the original amount that should be deducted from it.
apply_on
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 item price specified by item_price_id.
duration_type
required, 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. .
duration_month
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.
valid_till
optional, timestamp(UTC) in seconds
Date upto which the coupon can be applied to new subscriptions.
max_redemptions
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.

.
invoice_notes
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.
meta_data
optional, jsonobject
A set of key-value pairs stored as additional information for the subscription. Learn more.
included_in_mrr
optional, boolean
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.
period
optional, integer, min=1
The duration of time for which the coupon is attached to the subscription, in period_units. Applicable only when duration_type is limited_period.
period_unit
optional, enumerated string
The unit of time for period. Applicable only when duration_type is limited_period.
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.
status
optional, enumerated string, default=active
Status of the coupon.
Possible values are
activeCan be applied to a subscription.archivedCannot be applied to a subscription. Existing associations remain unaffected.
+
item_constraints
Parameters for item_constraints. Multiple item_constraints can be passed by specifying unique indices.
pass parameters as item_constraints[<param name>][<idx:0..n>]
item_constraints[constraint][0..n]
required, enumerated string
Constraint applicable for the item.
Possible values are
noneCoupon not applicable to any items.allCoupon applicable to all items.specificCoupon applicable to specific items.criteriaCoupon applicable based on criteria.
item_constraints[item_type][0..n]
required, enumerated string
Item type for which this criteria is applicable for.
Possible values are
planPlan.addonAddon.chargeCharge.
item_constraints[item_price_ids][0..n]
optional, jsonarray
List of item price ids for which this coupon is applicable.
+
item_constraint_criteria
Parameters for item_constraint_criteria. Multiple item_constraint_criteria can be passed by specifying unique indices.
pass parameters as item_constraint_criteria[<param name>][<idx:0..n>]
item_constraint_criteria[item_type][0..n]
optional, enumerated string
Item type for which this criteria is applicable for.
Possible values are
planPlan is a type of item.addonAddon is a type of item.chargeCharge is a type of item.
item_constraint_criteria[item_family_ids][0..n]
optional, jsonarray
List of families for which this coupon is applicable.
item_constraint_criteria[currencies][0..n]
optional, jsonarray
List of currencies (ISO 4217 format) for which this coupon is applicable.
item_constraint_criteria[item_price_periods][0..n]
optional, jsonarray
Pass the item price period units for this criterion. period followed by period_units. Such as [1 day,1 week,3 month,6 month].
always returned
Resource object representing coupon.
This API updates a coupon that is created for a specific promotion or offers.
Sample Request
curl  https://{site}.chargebee.com/api/v2/coupons/sample_coupon/update_for_items \
     -u {site_api_key}:\
     -d discount_percentage=20.0 \
     -d item_constraints[constraint][0]="all" \
     -d item_constraints[item_type][0]="plan" \
     -d item_constraints[constraint][1]="all" \
     -d item_constraints[item_type][1]="addon"
copy
curl  https://{site}.chargebee.com/api/v2/coupons/sample_coupon/update_for_items \
     -u {site_api_key}:\
     -d discount_percentage=20.0 \
     -d item_constraints[constraint][0]="all" \
     -d item_constraints[item_type][0]="plan" \
     -d item_constraints[constraint][1]="all" \
     -d item_constraints[item_type][1]="addon"

Sample Response [ JSON ]

Show more...
{"coupon": { "apply_discount_on": "not_applicable", "apply_on": "each_specified_item", "created_at": 1517495316, "discount_percentage": 20, "discount_type": "percentage", "duration_type": "forever", "id": "sample_coupon", "item_constraints": [ { "constraint": "all", "item_type": "plan" }, {..} ], "name": "Sample Coupon", "object": "coupon", "redemptions": 0, "resource_version": 1517495317068, "status": "active", "updated_at": 1517495317 }}

URL Format POST

https://{site}.chargebee.com/api/v2/coupons/{coupon_id}/update_for_items
name
optional, 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.

.
invoice_name
optional, string, max chars=100
Display name used in invoice. If it is not configured then name is used in invoice.
discount_type
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.
discount_amount
optional, in cents, min=0
The value of the deduction. The format of this value depends on the kind of currency.
currency_code
required if Multicurrency is enabled, string, max chars=3
The currency code (ISO 4217 format) of the coupon. Applicable for fixed_amount coupons alone.
discount_percentage
optional, double, min=0.01, max=100.0
The percentage of the original amount that should be deducted from it.
apply_on
optional, 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 item price specified by item_price_id.
duration_type
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. .
duration_month
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.
valid_till
optional, timestamp(UTC) in seconds
Date upto which the coupon can be applied to new subscriptions.
max_redemptions
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.

.
invoice_notes
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.
meta_data
optional, jsonobject
A set of key-value pairs stored as additional information for the subscription. Learn more.
included_in_mrr
optional, boolean
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.
period
optional, integer, min=1
The duration of time for which the coupon is attached to the subscription, in period_units. Applicable only when duration_type is limited_period.
period_unit
optional, enumerated string
The unit of time for period. Applicable only when duration_type is limited_period.
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.
+
item_constraints
Parameters for item_constraints. Multiple item_constraints can be passed by specifying unique indices.
pass parameters as item_constraints[<param name>][<idx:0..n>]
item_constraints[constraint][0..n]
required, enumerated string
Constraint applicable for the item.
Possible values are
noneCoupon not applicable to any items.allCoupon applicable to all items.specificCoupon applicable to specific items.criteriaCoupon applicable based on criteria.
item_constraints[item_type][0..n]
required, enumerated string
Item type for which this criteria is applicable for.
Possible values are
planPlan.addonAddon.chargeCharge.
item_constraints[item_price_ids][0..n]
optional, jsonarray
List of item price ids for which this coupon is applicable.
+
item_constraint_criteria
Parameters for item_constraint_criteria. Multiple item_constraint_criteria can be passed by specifying unique indices.
pass parameters as item_constraint_criteria[<param name>][<idx:0..n>]
item_constraint_criteria[item_type][0..n]
optional, enumerated string
Item type for which this criteria is applicable for.
Possible values are
planPlan is a type of item.addonAddon is a type of item.chargeCharge is a type of item.
item_constraint_criteria[item_family_ids][0..n]
optional, jsonarray
List of families for which this coupon is applicable.
item_constraint_criteria[currencies][0..n]
optional, jsonarray
List of currencies (ISO 4217 format) for which this coupon is applicable.
item_constraint_criteria[item_price_periods][0..n]
optional, jsonarray
Pass the item price period units for this criterion. period followed by period_units. Such as [1 day,1 week,3 month,6 month].
always returned
Resource object representing coupon.
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.
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": { "apply_discount_on": "not_applicable", "apply_on": "each_specified_item", "created_at": 1517495314, "discount_percentage": 10, "discount_type": "percentage", "duration_type": "forever", "id": "summer_offer", "item_constraints": [ { "constraint": "all", "item_type": "plan" }, {..} ], "name": "Summer Offer", "object": "coupon", "redemptions": 0, "resource_version": 1517495314967, "status": "active", "updated_at": 1517495314 }}, {..} ]}

URL Format GET

https://{site}.chargebee.com/api/v2/coupons
limit
optional, integer, default=10, min=1, max=100
The number of resources to be returned.
offset
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.
sort_by[<sort-order>]
optional, string filter
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.
Filter Params
For operator usages, see the Pagination and Filtering section.
id[<operator>]
optional, string filter

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.

.
Supported operators : is, is_not, starts_with, in, not_in

Example id[is_not] = "OFF2008"
name[<operator>]
optional, string filter

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.

.
Supported operators : is, is_not, starts_with, in, not_in

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

Example discount_type[is] = "fixed_amount"
duration_type[<operator>]
optional, enumerated string filter
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_not] = "forever"
status[<operator>]
optional, enumerated string filter
Status of the coupon. Possible values are : active, expired, archived, deleted.
Supported operators : is, is_not, in, not_in

Example status[is_not] = "active"
apply_on[<operator>]
optional, enumerated string filter
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] = "invoice_amount"
created_at[<operator>]
optional, timestamp(UTC) in seconds filter
Timestamp indicating when this coupon is created.
Supported operators : after, before, on, between

Example created_at[before] = "145222875"
updated_at[<operator>]
optional, timestamp(UTC) in seconds filter
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"
currency_code[<operator>]
optional, string filter
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"
always returned
Resource object representing coupon.
next_offset
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”.
This API retrieves a specific coupon using the coupon ID.
Sample Request
curl  https://{site}.chargebee.com/api/v2/coupons/demo_offer \
     -u {site_api_key}:
copy
curl  https://{site}.chargebee.com/api/v2/coupons/demo_offer \
     -u {site_api_key}:

Sample Response [ JSON ]

Show more...
{"coupon": { "apply_discount_on": "not_applicable", "apply_on": "each_specified_item", "created_at": 1517495364, "currency_code": "USD", "discount_amount": 500, "discount_type": "fixed_amount", "duration_type": "forever", "id": "demo_offer", "item_constraints": [ { "constraint": "all", "item_type": "plan" }, {..} ], "name": "Demo Offer", "object": "coupon", "redemptions": 0, "resource_version": 1517495364521, "status": "active", "updated_at": 1517495364 }}

URL Format GET

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

Sample admin console URL

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

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": { "apply_discount_on": "not_applicable", "apply_on": "invoice_amount", "created_at": 1517495315, "currency_code": "USD", "discount_amount": 500, "discount_type": "fixed_amount", "duration_type": "forever", "id": "beta", "name": "Beta", "object": "coupon", "redemptions": 0, "resource_version": 1612967315122, "status": "deleted", "updated_at": 1612967315 }}

URL Format POST

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

Copies a coupon over from one site to another. Copying of archived coupons is not supported.

The item prices that are linked to the coupon in the source site are also linked to the coupon in the destination site. However, this will only work if those item prices exist and with the same ids, in the destination site. Hence, it is recommended that the item prices be copied over before copying the coupons.

The value for redemptions is not copied. It is set to 0 for the newly created coupon. Hence, if such a coupon had expired in the source site due to redemptions having reached max_redemptions, it’s status would be active in the destination site.


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": { "apply_discount_on": "not_applicable", "apply_on": "each_specified_item", "created_at": 1517495314, "currency_code": "USD", "discount_amount": 100, "discount_type": "fixed_amount", "duration_type": "one_time", "id": "copy_coupon", "item_constraints": [ { "constraint": "all", "item_type": "plan" }, {..} ], "name": "Copy Coupon", "object": "coupon", "redemptions": 0, "resource_version": 1517495314819, "status": "active", "updated_at": 1517495314 }}

URL Format POST

https://{site}.chargebee.com/api/v2/coupons/copy
from_site
required, string, max chars=50
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), contact support to have this allow-listed.
id_at_from_site
required, string, max chars=100
Id of the coupon to be copied. The new coupon created in this site will have the same Id.
id
optional, string, max chars=100
Id of copied coupon in this site.
for_site_merging
optional, boolean, default=false
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.
always returned
Resource object representing coupon.
This API unarchives a specific coupon using the coupon 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": { "apply_discount_on": "not_applicable", "apply_on": "each_specified_item", "created_at": 1517495315, "currency_code": "USD", "discount_amount": 500, "discount_type": "fixed_amount", "duration_type": "forever", "id": "winter_offer", "item_constraints": [ { "constraint": "all", "item_type": "plan" }, {..} ], "name": "Winter Offer", "object": "coupon", "redemptions": 1, "resource_version": 1517495316871, "status": "active", "updated_at": 1517495316 }}

URL Format POST

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