# Coupons

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


## Overview[](#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[](#order-of-application-of-coupons)

When multiple [coupons](/docs/api/coupons) are applied to a [subscription](/docs/api/subscriptions) or [one-time invoice](/docs/api/v2/pcv-1/invoices/create-an-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 Coupon

```json
{
  "addon_constraint": "not_applicable",
  "apply_discount_on": "not_applicable",
  "apply_on": "invoice_amount",
  "created_at": 1517505786,
  "currency_code": "USD",
  "discount_amount": 500,
  "discount_type": "fixed_amount",
  "duration_type": "forever",
  "id": "sample_offer",
  "name": "Sample Offer",
  "object": "coupon",
  "plan_constraint": "not_applicable",
  "redemptions": 0,
  "resource_version": 1517505786000,
  "status": "active",
  "updated_at": 1517505786
}
```

## Coupons attributes

## Input Parameters

- `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.

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

- `invoice_name` (optional, string, max chars=100)
  Display name used in invoice. If it is not configured then name is used in invoice.

- `discount_type` (required, enumerated string, default=percentage)
  Specifies the type of discount to be applied.
  Possible enum values:
    - `fixed_amount`
      A fixed amount is deducted as a discount. The discount amount is specified in `[discount_amount](/docs/api/v2/pcv-1/coupons/coupon-object#discount_amount)`.
      
      [Learn more](https://www.chargebee.com/docs/1.0/coupons.html#fixed-amount) about `fixed_amount` coupons.
    - `percentage`
      A percentage of the original price is deducted as a discount. The discount percentage is specified in `[discount_percentage](/docs/api/v2/pcv-1/coupons/coupon-object#discount_percentage)`.
      
      [Learn more](https://www.chargebee.com/docs/1.0/coupons.html#percentage) about `percentage` coupons.
    - `offer_quantity`
      A specified number of units of the plan or addon are offered for free. The number of free units is specified in `[discount_quantity](/docs/api/v2/pcv-1/coupons/coupon-object#discount_quantity)`. The `offer_quantity` option is valid only when `[apply_on](/docs/api/v2/pcv-1/coupons/coupon-object#apply_on)` is set to `each_specified_item` and the `pricing_model` of the [plan](/docs/api/v2/pcv-1/plans/plan-object#pricing_model) or addon is `per_unit`.
      
      [Learn more](https://www.chargebee.com/docs/1.0/coupons.html#offer-quantity) about `offer_quantity` coupons.

- `discount_percentage` (optional, double, min=0.01, max=100)
  The percentage of the original amount that should be deducted from it.

- `discount_amount` (optional, in cents, min=0)
  The value of the deduction. The format of this value depends on the [kind of currency](/docs/api/currencies) .

- `discount_quantity` (optional, integer, min=1)
  Specifies the number of free units provided for the [plan](/docs/api/v2/pcv-1/plans) or [addon](/docs/api/v2/pcv-1/addons) , without affecting the total quantity sold. This parameter is applicable only when the `[discount_type](/docs/api/v2/pcv-1/coupons/coupon-object#discount_type)` is set to `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 coupon. Applicable for _fixed\_amount_ coupons alone.

- `duration_type` (required, enumerated string, default=forever)
  Specifies the time duration for which this coupon is attached to the subscription.
  Possible enum values:
    - `one_time`
      The coupon stays attached to the subscription till it is applied on an invoice **once**. It is removed after that from the subscription.
    - `forever`
      The coupon is attached to the subscription and applied on the invoices until explicitly removed.
    - `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` .

- `valid_till` (optional, timestamp(UTC) in seconds)
  Date upto which the coupon can be applied to new subscriptions.

- `max_redemptions` (optional, integer, min=1)
  Maximum number of times this coupon can be redeemed.
  
  **Note:**
  
  If not specified, the coupon can be redeemed an indefinite number of times.

- `status` (optional, enumerated string, default=active)
  Status of the coupon.
  Possible enum values:
    - `active`
      Can be applied to a subscription.
    - `expired`
      Cannot be applied to a subscription. A coupon may expire due to exceeding `[max_redemptions](/docs/api/coupons/coupon-object#max_redemptions)` or `[valid_till](/docs/api/coupons/coupon-object#valid_till)` date is past. Existing associations remain unaffected.
    - `archived`
      Cannot be applied to a subscription. Existing associations remain unaffected.
    - `deleted`
      Indicates the coupon has been deleted.

- `apply_on` (required, enumerated string)
  The amount on the invoice to which the coupon is applied.
  Possible enum values:
    - `invoice_amount`
      The coupon is applied to the invoice `sub_total` .
    - `each_specified_item`
      The coupon is applied to the `invoice.line_item.amount` that corresponds to the plan or addon specified by `plan_ids` and `addon_ids` .

- `plan_constraint` (required, enumerated string)
  Plans the coupon can be applied to.
  Possible enum values:
    - `none`
      Coupon not applicable to any plans.
    - `all`
      Coupon applicable to all plans.
    - `specific`
      Coupon applicable to specific plan(s).
    - `not_applicable`
      Coupon only applicable to invoice amount and not any plans.

- `addon_constraint` (required, enumerated string)
  Addons the coupon can be applied to.
  Possible enum values:
    - `none`
      Coupon not applicable to any addons.
    - `all`
      Coupon applicable to all addons.
    - `specific`
      Coupon applicable to specific addon(s).
    - `not_applicable`
      Coupon only applicable to invoice amount and not any addons.

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

- `archived_at` (optional, timestamp(UTC) in seconds)
  Timestamp indicating when this coupon was archived.

- `resource_version` (optional, long)
  The version number of this resource. For every change made to the resource, `resource_version` is updated with a new timestamp in milliseconds.

- `updated_at` (optional, timestamp(UTC) in seconds)
  Timestamp indicating when this coupon was last updated. Note that this does not change when the `[redemptions](/docs/api/coupons/coupon-object#redemptions)` attribute is changed. This attribute will be present only if the resource has been updated after 2016-11-09.

- `included_in_mrr` (optional, boolean)
  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` .

- `period` (optional, integer, min=1)
  The duration of time for which the coupon is attached to the subscription, in `period_units`. Applicable only when `[duration_type](/docs/api/coupons/coupon-object#duration_type)` is `[limited_period](/docs/api/coupons/coupon-object#duration_type)` .

- `period_unit` (optional, enumerated string)
  The unit of time for period. Applicable only when `[duration_type](/docs/api/coupons/coupon-object#duration_type)` is `[limited_period](/docs/api/coupons/coupon-object#duration_type)` .
  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.

- `plan_ids` (optional, string, max chars=100)
  List of plan ids for which this coupon is applicable.

- `addon_ids` (optional, string, max chars=100)
  List of addon ids for which this coupon is applicable.

- `redemptions` (optional, integer, min=0)
  The number of times this coupon has been redeemed.

- `invoice_notes` (optional, string, max chars=2000)
  A customer-facing note added to all invoices associated with this API resource. This note becomes one among [all the notes](/docs/api/invoices/invoice-object#notes) displayed on the invoice PDF.

- `meta_data` (optional, jsonobject)
  A collection of key-value pairs that provides extra information about the coupon.
  
  **Note:** There's a character limit of 65,535.
  
  [Learn more](/docs/api/v2/pcv-1/advanced-features) .

- `deleted` (required, boolean)
  Indicates whether the coupon is deleted or not.