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

**Note:**

If you wish to provide discounts to your customers via API or the Chargebee app, see [Discounts API](/docs/api/discounts)

## 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

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 Coupon

```json
{
  "apply_discount_on": "not_applicable",
  "apply_on": "each_specified_item",
  "created_at": 1517495314,
  "discount_percentage": 10,
  "discount_type": "percentage",
  "duration_type": "forever",
  "id": "summer_offer",
  "item_constraints": [
    {
      "constraint": "all",
      "item_type": "plan"
    },
    {..}
  ],
  "name": "Summer Offer",
  "object": "coupon",
  "redemptions": 0,
  "resource_version": 1517495314967,
  "status": "active",
  "updated_at": 1517495314
}
```

## 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/coupons/coupon-object#discount_amount)`.
      
      [Learn more](https://www.chargebee.com/docs/2.0/coupons.html#fixed-amount-coupons) 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/coupons/coupon-object#discount_percentage)`.
      
      [Learn more](https://www.chargebee.com/docs/2.0/coupons.html#percentage-coupons) about `percentage` coupons.
    - `offer_quantity`
      A specified number of units of the item price are offered for free. The number of free units is specified in `[discount_quantity](/docs/api/coupons/coupon-object#discount_quantity)`. The `offer_quantity` option is valid only when `[apply_on](/docs/api/coupons/coupon-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`.
      
      [Learn more](https://www.chargebee.com/docs/2.0/coupons.html#offer-quantity-coupons) 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 [item price](/docs/api/item_prices) , without affecting the total quantity sold. This parameter is applicable only when the `[discount_type](/docs/api/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_from` (optional, timestamp(UTC) in seconds)
  The date from which the coupon can be applied to subscriptions.

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

- `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`
      Applies the coupon to specified items (plans, addons, or charges), with the discount applied to each matching `invoice.line_item.amount`.
      
      Requires applicability to be configured using [`item_constraints`](/docs/api/coupons/coupon-object#item_constraints)—for example `all`, `criteria`, or `specific` with `item_price_ids`.
      
      When you attach this coupon to a subscription, at least one of that subscription's plans, addons, or charges must match those rules. If none do, the request fails.

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

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

- `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/advanced-features) .

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

- `item_constraints` (optional, list of item_constraint)
  The list of item constraints.
  - `item_type` (required, enumerated string)
    Item type for which this criteria is applicable for.
    Possible enum values:
      - `plan`
        Plan
      - `addon`
        Addon
      - `charge`
        Charge
  - `constraint` (required, enumerated string)
    Constraint applicable for the item
    Possible enum values:
      - `none`
        Coupon not applicable to any items.
      - `all`
        Coupon applicable to all items.
      - `specific`
        Coupon applicable to specific items.
      - `criteria`
        Coupon applicable based on criteria.
  - `item_price_ids` (optional)
    List of item price ids for which this coupon is applicable.

- `item_constraint_criteria` (optional, list of item_constraint_criteria)
  The list of item constraint criteria.
  - `item_type` (required, enumerated string)
    Item type for which this criteria is applicable for.
    Possible enum values:
      - `plan`
        Plan is a type of item
      - `addon`
        Addon is a type of item
      - `charge`
        Charge is a type of item
  - `currencies` (optional)
    List of currencies ([ISO 4217 format](https://www.chargebee.com/docs/supported-currencies.html) ) for which this coupon is applicable.
  - `item_family_ids` (optional)
    List of families for which this coupon is applicable.
  - `item_price_periods` (optional)
    List of frequencies for which this coupon is applicable. Allowed frequencies are \[day, week, month, year\].

- `coupon_constraints` (optional, list of coupon_constraint)
  List of constraints applicable on the redemption of this coupon.
  - `entity_type` (required, enumerated string)
    The resource type for the constraint. This, along with `type` and `value` , helps define the specific rule applied.
    Possible enum values:
      - `customer`
        The constraint is based on `customer` records.
  - `type` (required, enumerated string)
    Type of coupon constraints
    Possible enum values:
      - `max_redemptions`
        The coupon can be redeemed up to a set number of times for a specific resource type. The maximum redemptions are specified using `value` , and the resource type is specified using `entity_type`. For example, if `entity_type` is `customer` and `value` is `10` then the coupon can only be redeemed up to 10 times for any particular `customer` record.
      - `unique_by`
        Indicates - when `entity_type` is `customer`
        
        -   that the coupon can be redeemed only once for every unique value of a specified `customer` attribute. The `customer` attribute is specified using `value`. For example, if `value` is `email` , then the coupon can be redeemed only once for every unique value of `customer.email`. In other words, when there are multiple `customer` records with the same value for `email` , once the coupon has been redeemed for one of those customer records, no further redemptions of the coupon are allowed for any of those `customer` records.
      - `existing_customer`
        The coupon is applicable only for existing customer(s). A customer will be considered as `existing_customer` when they have at least one non-void, non-zero-dollar invoice.
      - `new_customer`
        The coupon is applicable only for new customer(s). A customer will be considered as `new_customer` when they do not have any prior non-void, non-zero-dollar invoices.
  - `value` (optional, string, max chars=65k)
    The value of the coupon constraint. The possible values depend on the value of `constraints[type]`:
    
    -   When `type` is `unique_by`, then `value` can be `email` or `id`.
        
    -   When `type` is `max_redemptions`, then `value` can be any integer in the range `1` `coupon.max_redemptions`, inclusive.
        
    -   When type is `new_customer` or `existing_customer` then `value` can be `based_on_invoice`.