Settings
Configure SDK
Coupons
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
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.
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.
The value of the deduction. The format of this value depends on the kind of currency .
Specifies the number of free units provided for the item price
, without affecting the total quantity sold. This parameter is applicable only when the discount_type
is set to offer_quantity
.
The currency code (ISO 4217 format ) of the coupon. Applicable for fixed_amount coupons alone.
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.
The duration of time for which the coupon is attached to the subscription, in period_units.
Applicable only when duration_type
is limited_period
.
The unit of time for period. Applicable only when duration_type
is limited_period
.
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.
A collection of key-value pairs that provides extra information about the coupon.
Note: There's a character limit of 65,535.
The list of item constraints.
The list of item constraint criteria.
List of constraints applicable on the redemption of this coupon.
Create a coupon for items ¶
This API creates a new coupon for a specific promotion or offers.
Sample Response [ JSON ]
URL Format POST
Input Parameters
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.
.
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.
.
The value of the deduction. The format of this value depends on the kind of currency .
The currency code (ISO 4217 format ) of the coupon. Applicable for fixed_amount coupons alone.
Specifies the number of free units provided for the item price
, without affecting the total quantity sold. This parameter is applicable only when the discount_type
is set to offer_quantity
.
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.
A collection of key-value pairs that provides extra information about the coupon.
Note: There's a character limit of 65,535.
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
.
The duration of time for which the coupon is attached to the subscription, in period_units.
Applicable only when duration_type
is limited_period
.
The unit of time for period. Applicable only when duration_type
is limited_period
.
pass parameters as item_constraints[<param name>][<idx:0..n>]
pass parameters as item_constraint_criteria[<param name>][<idx:0..n>]
pass parameters as coupon_constraints[<param name>][<idx:0..n>]
Returns
Resource object representing coupon
Update a coupon for items ¶
This API updates a coupon that is created for a specific promotion or offers.
Sample Response [ JSON ]
URL Format POST
Input Parameters
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.
.
The value of the deduction. The format of this value depends on the kind of currency .
The currency code (ISO 4217 format ) of the coupon. Applicable for fixed_amount coupons alone.
Specifies the number of free units provided for the item price
, without affecting the total quantity sold. This parameter is applicable only when the discount_type
is set to offer_quantity
.
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.
A collection of key-value pairs that provides extra information about the coupon.
Note: There's a character limit of 65,535.
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
.
The duration of time for which the coupon is attached to the subscription, in period_units.
Applicable only when duration_type
is limited_period
.
The unit of time for period. Applicable only when duration_type
is limited_period
.
pass parameters as item_constraints[<param name>][<idx:0..n>]
pass parameters as item_constraint_criteria[<param name>][<idx:0..n>]
pass parameters as coupon_constraints[<param name>][<idx:0..n>]
Returns
Resource object representing coupon
List coupons ¶
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 Response [ JSON ]
URL Format GET
Input Parameters
Filter Params
For operator usages, see the Pagination and Filtering section.
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] = "OFF2008"
Supported operators : is, is_not, starts_with, in, not_in
Example → id[is] = "OFF2008"
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_not] = "Offer 10"
Supported operators : is, is_not, starts_with, in, not_in
Example → name[is] = "Offer 10"
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[on] = "1243545465"
Supported operators : after, before, on, between
Example → updated_at[after] = "1243545465"
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"
Supported operators : is, is_not, starts_with, in, not_in
Example → currency_code[is] = "USD"
Returns
Resource object representing coupon
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`.
Retrieve a coupon ¶
This API retrieves a specific coupon using the coupon ID.
Sample Response [ JSON ]
URL Format GET
Returns
Resource object representing coupon
Sample admin console URL
Delete a coupon ¶
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 Response [ JSON ]
URL Format POST
Returns
Resource object representing coupon
Copy a 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.
Sample Response [ JSON ]
URL Format POST
Input Parameters
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.
Returns
Resource object representing coupon
Unarchive a coupon ¶
This API unarchives a specific coupon using the coupon ID.
Sample Response [ JSON ]
URL Format POST
Returns
Resource object representing coupon