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.
Order of application of coupons
When multiple coupons are applied 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, percentage coupons | coupon with apply_on = each_specified_item and discount_type = percentage |
| 3 | Invoice-level, fixed amount coupons | coupon with apply_on = invoice_amount and discount_type = flat |
| 4 | Invoice-level, percentage coupons | coupon with apply_on = invoice_amount and discount_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 coupon on the invoice
- a 1% off coupon on the addon
- a flat $10 coupon on the plan
The above coupons 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 | Flat $10 coupon on the plan | $(200 - 10) + $20 = $190 + $20 = $210 |
| 3 | 1% off coupon on the addon | $190 + $(20 - 0.2) = $190 + $19.8 = $209.8 |
| 4 | Flat $5 coupon on the invoice | $209.8 - $5 = $204.8 |
Sample CouponJSON
Coupons attributes
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.
Display name used in invoice. If it is not configured then name is used in invoice.
Specifies the type of discount to be applied.
A fixed amount is deducted as a discount. The discount amount is specified in discount_amount.
Learn more
about fixed_amount
coupons.
A percentage of the original price is deducted as a discount. The discount percentage is specified in discount_percentage.
Learn more
about percentage
coupons.
A specified number of units of the plan or addon are offered for free. The number of free units is specified in discount_quantity.
The offer_quantity
option is valid only when apply_on
is set to each_specified_item
and the pricing_model
of the plan
or addon is per_unit.
Learn more
about offer_quantity
coupons.
The percentage of the original amount that should be deducted from it.
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 plan
or addon
, 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.
Specifies the time duration for which this coupon is attached to the subscription.
The coupon stays attached to the subscription till it is applied on an invoice once. It is removed after that from the subscription.
The coupon is attached to the subscription and applied on the invoices until explicitly removed.
The 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
.
Date upto which the coupon can be applied to new subscriptions.
Maximum number of times this coupon can be redeemed.
Note:
If not specified, the coupon can be redeemed an indefinite number of times.
Status of the coupon.
Can be applied to a subscription.
Cannot be applied to a subscription. A coupon may expire due to exceeding max_redemptions
or valid_till
date is past. Existing associations remain unaffected.
Cannot be applied to a subscription. Existing associations remain unaffected.
Indicates the coupon has been deleted.
The amount on the invoice to which the coupon is applied.
The coupon is applied to the invoice sub_total
.
The coupon is applied to the invoice.line_item.amount
that corresponds to the plan or addon specified by plan_ids
and addon_ids
.
Plans the coupon can be applied to.
Coupon not applicable to any plans.
Coupon applicable to all plans.
Coupon applicable to specific plan(s).
Coupon only applicable to invoice amount and not any plans.
Addons the coupon can be applied to.
Coupon not applicable to any addons.
Coupon applicable to all addons.
Coupon applicable to specific addon(s).
Coupon only applicable to invoice amount and not any addons.
The version number of this resource. For every change made to the resource, resource_version
is updated with a new timestamp in milliseconds.
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 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
.
A period of 24 hours.
A period of 7 days.
A period of 1 calendar month.
A period of 1 calendar year.
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.