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 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 item price 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 item price 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 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.
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
.
The date from which the coupon can be applied to subscriptions.
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 coupon is scheduled to start at a future date and cannot be applied to a subscription. From the valid_from date, the status changes to active.
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 item price specified by item_price_id
.
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 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.
The list of item constraint criteria.