Beta Feature

The Discounts API is currently in beta. Contact eap@chargebee.com to get on the Early Adopter Program.

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:

Estimates

A discount can be added to an estimate using the following endpoints:

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.

Sample discount [ JSON ]

{ "id": "__dev__KyVmqWSHMbJxp2", "name": "__dev__KyVmqWSHMbJxp2", "invoice_name": "10% Off", "percentage": 10.0, "duration_type": "limited_period", "period": 3, "period_unit": "month", "apply_on": "specific_item_price", "item_price_id": "plan1", "included_in_mrr": "true", "created_at": 1605792731, "updated_at": 1605792731, "resource_version": 1605792731000, "applied_count": 1, "object": "discounts", "apply_till": 1599831828 }
id
An immutable unique id for the discount. It is always auto-generated.
string, max chars=50
invoice_name
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.
optional, string, max chars=100
type
The type of discount. Possible value are:.
enumerated string, default=percentage
Possible values are
fixed_amountThe specified amount will be given as discount.percentageThe specified percentage will be given as discount.
percentage
The percentage of the original amount that should be deducted from it. Only applicable when discount.type is percentage.
optional, double, min=0.01, max=100.0
amount
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.
optional, in cents, min=0
currency_code
The currency code (ISO 4217 format) of the discount. This is only applicable when discount.type is fixed_amount.
optional, string, max chars=3
duration_type
Specifies the time duration for which this discount is attached to the subscription.
enumerated string, default=forever
Possible values are
one_timeThe discount stays attached to the subscription till it is applied on an invoice once. It is removed after that from the subscription.foreverThe discount is attached to the subscription and applied on the invoices till it is 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.
period
The duration of time for which the discount is attached to the subscription, in period_units. Applicable only when duration_type is limited_period.
optional, integer, min=1
period_unit
The unit of time for period. Applicable only when duration_type is limited_period.
optional, enumerated string
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.
included_in_mrr
Set this to false if this coupon should be excluded from monthly recurring revenue (MRR) calculations for the site. The following prerequisites must be met to allow this parameter to be passed:
  • The discount duration_type must be one_time.
  • The feature must be enabled in Chargebee.
  • The site-level setting must be to include coupons in MRR calculations. The site level setting is also the default value for the attribute when this parameter is not passed.
.
boolean
apply_on
The amount on the invoice to which the discount is applied.
enumerated string
Possible values are
invoice_amountThe discount is applied to the invoice sub_total.specific_item_priceThe discount is applied to the invoice.line_item.amount that corresponds to the item price specified by item_price_id.
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.
optional, string, max chars=100
created_at
Timestamp indicating when this discount is created.
timestamp(UTC) in seconds
apply_till
Specifies till when the limited period discount is applicable. This attribute will be sent in the response only for limited_period duration type discount.
optional, timestamp(UTC) in seconds
applied_count
Specifies the number of times the discount has been applied.
optional, integer