A discount, just like coupons, represents a deduction from the amounts in an invoice. While coupons are typically used by your customers, discounts can be directly applied to subscriptions by your sales team while negotiating new deals or upgrades. If the negotiations are on the price itself, the price override feature helps adjust the price further.
Although a discount appears as a deduction on an invoice, it is applied to a subscription while creating or updating the subscription. Every discount in Chargebee is attached to only one subscription.
Note:
- The sum of the line-item-level and invoice-level coupons together for a subscription, cannot exceed 10.
- When discounts are enabled in Chargebee, the multi-coupons feature is automatically activated.
Adding a discount
Subscriptions
A discount can be added to a subscription by calling either Create subscription or Update subscription. Once added, the discount is applied to all subsequent invoices if apply_on is set to invoice_amount. When apply_on = specific_item_price, the discount is applied (as a discount.line_item_discount) in each invoice of the subscription that contains the specified item.
Invoices
A discount can be added to an invoice using Create invoice for items and one-time charges using the discounts parameter.
Quotes
A discount can be added to a quote using the following operations:
- Create a quote for new subscription
- Create a quote for updating a subscription
- Create a quote for charge and charge item
- Edit a quote for a new subscription
- Edit a quote for updating a subscription
- Edit a quote for charge items and charges
Estimates
A discount can be added to an estimate using the following endpoints:
- Estimate for creating a subscription.
- Estimate for creating a customer and subscription
- Estimate for updating a subscription
Removing a discount
Subscriptions
A discount can be removed by calling Update subscription with the relevant discounts[operation_type][] set to remove. Also, discounts that have duration_type as one_time or limited_period are removed automatically upon expiry.
Quotes
A discount can be removed from a quote using the following operations:
Estimates
A discount can be removed from an estimate using the following operation:
Listing discounts
A discount is associated with exactly one subscription. You can fetch all the discounts currently attached to a subscription by calling the List discounts for a subscription API or by passing include_discounts as true while creating, importing, updating or retrieving a subscription.
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 | Line-level, offer quantity coupons | coupon with apply_on = each_specified_item and discount_type = offer_quantity |
| 6 | Line-level, offer quantity discounts | discount with apply_on = specific_item_price and discount_type = offer_quantity |
| 7 | Invoice-level, fixed amount coupons | coupon with apply_on = invoice_amount and discount_type = flat |
| 8 | Invoice-level, fixed amount discounts | discount with apply_on = invoice_amount and type = fixed_amount |
| 9 | Invoice-level, percentage coupons | coupon with apply_on = invoice_amount and discount_type = percentage |
| 10 | 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 DiscountJSON
Discounts attributes
An immutable unique id for the discount. It is always auto-generated.
The name of the discount as it should appear on customer-facing pages and documents such as invoices
and hosted pages.
This is auto-generated based on the type
, amount
, and currency_code
of the discount. For example, it can be 10% off
or 10$ off
.
The type of discount. Possible value are:
The specified amount will be given as discount.
The specified percentage will be given as discount.
A specified number of units of the item price are offered for free. The number of free units is specified in 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
.
The percentage of the original amount that should be deducted from it. Only applicable when discount.type
is percentage.
The value of the discount. The format of this value
depends on the kind of currency. This is only applicable when discount.type
is fixed_amount.
Specifies the number of free units provided for the item, without affecting the total quantity sold. This parameter is applicable only when discount.type
is offer_quantity.
The currency code (ISO 4217 format
) of the discount. This is only applicable when discount.type
is fixed_amount
.
Specifies the time duration for which this discount is attached to the subscription.
The discount stays attached to the subscription till it is applied on an invoice once. It is removed after that from the subscription.
The discount is attached to the subscription and applied on the invoices till it is 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 duration of time for which the discount 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.
The discount is included in MRR calculations for your site. This attribute is only applicable when duration_type
is one_time
and when the feature is enabled
in Chargebee. Also, If the site-level setting
is to exclude one-time discounts from MRR calculations, this value is always returned false.
The amount on the invoice to which the discount is applied.
The discount is applied to the invoice sub_total
.
The discount is applied to the invoice.line_item.amount
that corresponds to the item price specified by item_price_id
.
The id of the item price
in the subscription to which the discount is to be applied. Relevant only when apply_on
= specific_item_price.
Specifies till when the limited period discount is applicable. This attribute will be sent in the response only for limited_period
duration type discount.
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.