# Discounts

> For the complete machine-readable documentation index, see [llms.txt](https://apidocs.chargebee.com/llms.txt).


A `discount`, just like `[coupons](/docs/api/coupons)`, represents a deduction from the amounts in an `invoice`. While coupons are typically used by your customers, `discount`s 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](
https://www.chargebee.com/docs/price-override.html#api) 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](https://www.chargebee.com/docs/coupons.html#applying-multiple-coupons-to-a-subscription) is automatically activated.

## Adding a discount[](#adding-a-discount)

### Subscriptions[](#subscriptions)

A `discount` can be added to a `subscription` by calling either [Create subscription](/docs/api/subscriptions/create-subscription-for-items) or [Update subscription](/docs/api/subscriptions/update-subscription-for-items). 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[](#invoices)

A `discount` can be added to an `invoice` using [Create invoice for items and one-time charges](/docs/api/invoices/create-invoice-for-items-and-one-time-charges) using the `discounts` parameter.

### Quotes[](#quotes)

A `discount` can be added to a `quote` using the following operations:

-   [Create a quote for new subscription](/docs/api/quotes/create-a-quote-for-a-new-subscription-items)
-   [Create a quote for updating a subscription](/docs/api/quotes/create-a-quote-for-update-subscription-items)
-   [Create a quote for charge and charge item](/docs/api/quotes/create-a-quote-for-charge-and-charge-items)
-   [Edit a quote for a new subscription](/docs/api/quotes/edit-create-subscription-quote-for-items)
-   [Edit a quote for updating a subscription](/docs/api/quotes/edit-update-subscription-quote-for-items)
-   [Edit a quote for charge items and charges](/docs/api/quotes/edit-quote-for-charge-items-and-charges)

### Estimates[](#estimates)

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

-   [Estimate for creating a subscription.](/docs/api/estimates/estimate-for-creating-a-subscription)
-   [Estimate for creating a customer and subscription](/docs/api/estimates/estimate-for-creating-a-customer-and-subscription)
-   [Estimate for updating a subscription](/docs/api/estimates/estimate-for-updating-a-subscription)

## Removing a discount[](#removing-a-discount)

### Subscriptions[](#subscriptions)

A `discount` can be removed by calling [Update subscription](/docs/api/subscriptions/update-subscription-for-items) 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[](#quotes)

A discount can be removed from a quote using the following operations:

-   [Edit a quote for a new subscription](/docs/api/quotes/edit-create-subscription-quote-for-items)
-   [Edit a quote for updating a subscription](/docs/api/quotes/edit-update-subscription-quote-for-items)

### Estimates[](#estimates)

A discount can be removed from an estimate using the following operation:

-   [Estimate for updating a subscription](/docs/api/estimates/estimate-for-updating-a-subscription)

## Listing discounts[](#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](/docs/api/subscriptions/list-discounts-for-a-subscription) or by passing `include_discounts` as `true` while creating, importing, updating or retrieving a subscription.

## Order of application of coupons and discounts[](#order-of-application-of-coupons-and-discounts)

When both [coupons](/docs/api/coupons) and [discounts](/docs/api/discounts) are applied simultaneously to a [subscription](/docs/api/subscriptions) or [one-time invoice](/docs/api/invoices/create-invoice-for-items-and-one-time-charges), 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 Discount

```json
{
  "id": "__dev__KyVmqWSHMbJxp2",
  "name": "__dev__KyVmqWSHMbJxp2",
  "invoice_name": "10% Off",
  "percentage": 10,
  "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
}
```

## Discounts attributes

## Input Parameters

- `id` (required, string, max chars=50)
  An immutable unique id for the discount. It is always auto-generated.

- `invoice_name` (optional, string, max chars=100)
  The name of the discount as it should appear on customer-facing pages and documents such as [invoices](/docs/api/invoices) and [hosted pages](/docs/api/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` .

- `type` (required, enumerated string, default=percentage)
  The type of discount. Possible value are:
  Possible enum values:
    - `fixed_amount`
      The specified amount will be given as discount.
    - `percentage`
      The specified percentage will be given as discount.
    - `offer_quantity`
      A specified number of units of the item price are offered for free. The number of free units is specified in `[quantity](/docs/api/discounts)`. The `offer_quantity` option is valid only when `[apply_on](/docs/api/discounts/discount-object#apply_on)` is set to `each_specified_item` and the `[pricing_model](/docs/api/item_prices/item_price-object#pricing_model)` of the item price is `per_unit` .

- `percentage` (optional, double, min=0.01, max=100)
  The percentage of the original amount that should be deducted from it. Only applicable when `discount.type` is `percentage`.

- `amount` (optional, in cents, min=0)
  The value of the discount. [The format of this value](/docs/api/currencies) depends on the kind of currency. This is only applicable when `discount.type` is `fixed_amount`.

- `quantity` (optional, integer, min=1)
  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`.

- `currency_code` (optional, string, max chars=3)
  The currency code ([ISO 4217 format](https://www.chargebee.com/docs/supported-currencies.html) ) of the discount. This is only applicable when `discount.type` is `fixed_amount` .

- `duration_type` (required, enumerated string, default=forever)
  Specifies the time duration for which this discount is attached to the subscription.
  Possible enum values:
    - `one_time`
      The discount stays attached to the subscription till it is applied on an invoice **once**. It is removed after that from the subscription.
    - `forever`
      The discount is attached to the subscription and applied on the invoices till it is [explicitly removed](/docs/api/subscriptions/update-subscription-for-items#discounts_operation_type) .
    - `limited_period`
      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` .

- `period` (optional, integer, min=1)
  The duration of time for which the discount is attached to the subscription, in `period_units`. Applicable only when `duration_type` is `limited_period`.

- `period_unit` (optional, enumerated string)
  The unit of time for `period`. Applicable only when `duration_type` is `limited_period`.
  Possible enum values:
    - `day`
      A period of 24 hours.
    - `week`
      A period of 7 days.
    - `month`
      A period of 1 calendar month.
    - `year`
      A period of 1 calendar year.

- `included_in_mrr` (required, boolean)
  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](https://www.chargebee.com/docs/reporting.html#dashboards_flexible-mrr-calculation) in Chargebee. Also, If the [site-level setting](https://www.chargebee.com/docs/reporting.html#chart_flexible-mrr-calculation) is to exclude one-time discounts from MRR calculations, this value is always returned `false`.

- `apply_on` (required, enumerated string)
  The amount on the invoice to which the discount is applied.
  Possible enum values:
    - `invoice_amount`
      The discount is applied to the invoice `sub_total` .
    - `specific_item_price`
      The discount is applied to the `invoice.line_item.amount` that corresponds to the item price specified by `item_price_id` .

- `item_price_id` (optional, string, max chars=100)
  The [id of the item price](/docs/api/subscriptions/subscription-object#subscription_items_item_price_id) in the subscription to which the discount is to be applied. Relevant only when `apply_on` = `specific_item_price`.

- `created_at` (required, timestamp(UTC) in seconds)
  Timestamp indicating when this discount is created.

- `apply_till` (optional, timestamp(UTC) in seconds)
  Specifies till when the limited period discount is applicable. This attribute will be sent in the response only for `limited_period` duration type discount.

- `applied_count` (optional, integer)
  Specifies the number of times the discount has been applied.

- `coupon_id` (required, string, max chars=100)
  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](https://www.urlencoder.org/) the coupon ID in the path parameter before making an API call.

- `index` (required, integer, min=0)
  The index number of the subscription to which the item price is added. Provide a unique number between `0` and `4` (inclusive) for each subscription that is to be created.