Update A Coupon For Items

The device from which the customer has made the request

The email address of your customer/user. Use this when the email address has only ASCII characters.

The Base64-encoded email address of your customer/user. Use this if the email address has UTF-8 characters. When this header is provided, the header chargebee-request-origin-user is ignored.

The IP address of the customer where the request originated

skip all actions to be done on the events

One ofall-disabled

skip only emails

One ofall-disabled

skip only webhooks

One ofall-disabled

If the site has multiple business entities, you can use this custom HTTP header to specify the business entity for which Chargebee should perform the operation.

<p class="mb-2">The display name used in web interface for identifying the coupon.</p> <div class="alert alert-info"><p class="mb-2"><strong class="font-semibold">Note:</strong></p><p class="mb-2">When the name of the coupon set contains a special character; for example: <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">#</code>, the API returns an error. Make sure that you <a href="https://www.urlencoder.org/">encode</a> the name of the coupon set in the path parameter before making an API call.</p></div> <p class="mb-2">.</p>

Display name used in invoice. If it is not configured then name is used in invoice.

<p class="mb-2">Specifies the type of discount to be applied.</p> * percentage - <p class="mb-2">A percentage of the original price is deducted as a discount. The discount percentage is specified in <code><a href="/docs/api/coupons/update-a-coupon-for-items#discount_percentage">discount_percentage</a></code>.</p> <div class="alert alert-info"><p class="mb-2"><a href="https://www.chargebee.com/docs/2.0/coupons.html#percentage-coupons">Learn more</a> about <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">percentage</code> coupons.</p></div> * fixed_amount - <p class="mb-2">A fixed amount is deducted as a discount. The discount amount is specified in <code><a href="/docs/api/coupons/update-a-coupon-for-items#discount_amount">discount_amount</a></code>.</p> <div class="alert alert-info"><p class="mb-2"><a href="https://www.chargebee.com/docs/2.0/coupons.html#fixed-amount-coupons">Learn more</a> about <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">fixed_amount</code> coupons.</p></div> * offer_quantity - <p class="mb-2">A specified number of units of the item price are offered for free. The number of free units is specified in <code><a href="/docs/api/coupons/update-a-coupon-for-items#discount_quantity">discount_quantity</a></code>. The <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">offer_quantity</code> option is valid only when <code><a href="/docs/api/coupons/update-a-coupon-for-items#apply_on">apply_on</a></code> is set to <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">each_specified_item</code> and the <code><a href="/docs/api/item_prices/item_price-object#pricing_model">pricing_model</a></code> of the item price is <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">per_unit</code>.</p> <div class="alert alert-info"><p class="mb-2"><a href="https://www.chargebee.com/docs/2.0/coupons.html#offer-quantity-coupons">Learn more</a> about <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">offer_quantity</code> coupons.</p></div>

One offixed_amountpercentageoffer_quantityDefault "percentage"

The value of the deduction. The format of this value depends on the [kind of currency](/docs/api/currencies) .

The currency code ([ISO 4217 format](https://www.chargebee.com/docs/2.0/supported-currencies.html) ) of the coupon. Applicable for *fixed_amount* coupons alone.

The percentage of the original amount that should be deducted from it.

<p class="mb-2">Specifies the number of free units provided for the <a href="/docs/api/item_prices">item price</a> , without affecting the total quantity sold. This parameter is applicable only when the <code><a href="/docs/api/coupons/update-a-coupon-for-items#discount_type">discount_type</a></code> is set to <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">offer_quantity</code> .</p>

<p class="mb-2">The amount on the invoice to which the coupon is applied.</p> * invoice_amount - <p class="mb-2">The coupon is applied to the invoice <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">sub_total</code> .</p> * each_specified_item - <p class="mb-2">Applies the coupon to specified items (plans, addons, or charges), with the discount applied to each matching <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">invoice.line_item.amount</code>.</p> <p class="mb-2">Requires applicability to be configured using <a href="/docs/api/coupons/update-a-coupon-for-items#item_constraints" class="text-blue-600 hover:text-blue-800 underline"><code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">item_constraints</code></a>—for example <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">all</code>, <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">criteria</code>, or <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">specific</code> with <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">item_price_ids</code>.</p> <p class="mb-2">When you attach this coupon to a subscription, at least one of that subscription&#x27;s plans, addons, or charges must match those rules. If none do, the request fails.</p>

One ofinvoice_amounteach_specified_item

<p class="mb-2">Specifies the time duration for which this coupon is attached to the subscription.</p> * forever - <p class="mb-2">The coupon is attached to the subscription and applied on the invoices until explicitly removed.</p> * one_time - <p class="mb-2">The coupon stays attached to the subscription till it is applied on an invoice <strong class="font-semibold">once</strong>. It is removed after that from the subscription.</p> * limited_period - <p class="mb-2">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 <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">period</code> and <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">period_unit</code> .</p>

One ofone_timeforeverlimited_periodDefault "forever"

<p class="mb-2"><strong class="font-semibold">(Deprecated)</strong> The duration of time in months for which the coupon is attached to the subscription. Applicable only when <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">duration_type</code> is <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">limited_period</code>.</p> <p class="mb-2"><strong class="font-semibold">Note:</strong> This parameter has been deprecated. Use <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">period</code> and <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">period_unit</code> instead.</p>

The date from which the coupon can be applied to subscriptions.

Date upto which the coupon can be applied to new subscriptions.

Maximum number of times this coupon can be redeemed. **Note:** If not specified, the coupon can be redeemed an indefinite number of times. .

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.

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

<p class="mb-2">The coupon is included in MRR calculations for your site. This attribute is only applicable for coupons of <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">duration_type = one_time</code> 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 <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">false</code> .</p>

<p class="mb-2">The duration of time for which the coupon is attached to the subscription, in <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">period_units</code>. Applicable only when <code><a href="/docs/api/coupons/coupon-object#duration_type">duration_type</a></code> is <code><a href="/docs/api/coupons/coupon-object#duration_type">limited_period</a></code> .</p>

<p class="mb-2">The unit of time for period. Applicable only when <code><a href="/docs/api/coupons/coupon-object#duration_type">duration_type</a></code> is <code><a href="/docs/api/coupons/coupon-object#duration_type">limited_period</a></code> .</p> * month - <p class="mb-2">A period of 1 calendar month.</p> * week - <p class="mb-2">A period of 7 days.</p> * year - <p class="mb-2">A period of 1 calendar year.</p> * day - <p class="mb-2">A period of 24 hours.</p>

One ofdayweekmonthyear

Parameters for item_constraints

<p class="mb-2">List of item price ids for which this coupon is applicable.</p> <div class="alert alert-info"><p class="mb-2"><strong class="font-semibold">Note:</strong></p><p class="mb-2">When specifying a value for <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">item_price_ids</code>, make sure that the value is wrapped in square brackets (<code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">[]</code>), for example: <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">[cbdemo_advanced-USD-Daily]</code> instead of <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">cbdemo_advanced-USD-Daily</code>; otherwise, a <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">param_wrong_value</code> error returns.</p><p class="mb-2">For information about <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">item_price_ids</code>, refer to <em class="italic">Defining Price Points</em> in <a href="https://www.chargebee.com/docs/2.0/plans.html#defining-price-points-for-plan" target="_blank">Plans</a>, <a href="https://www.chargebee.com/docs/2.0/addons.html#defining-price-points-for-an-addon" target="_blank">Addons</a>, and <a href="https://www.chargebee.com/docs/2.0/charges.html#defining-price-points-for-a-charge" target="_blank">Charges</a>.</p></div>

Parameters for item_constraint_criteria

List of families for which this coupon is applicable.

List of currencies ([ISO 4217 format](https://www.chargebee.com/docs/supported-currencies.html) ) for which this coupon is applicable.

<p class="mb-2">Pass the item price period units for this criterion. <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">period</code> followed by <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">period_units</code>. Such as <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">[1 day,1 week,3 month,6 month]</code></p>

<p class="mb-2">Parameters for <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">coupon_constraints</code>. Multiple <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">coupon_constraints</code> can be passed by specifying unique indices.</p>

<p class="mb-2">The value of the coupon constraint. The possible values depend on the value of <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">constraints[type]</code>:</p> <ul class="list-disc list-outside ml-6 my-4 space-y-2"> <li class="text-base leading-relaxed"> <p class="mb-2">When <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">type</code> is <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">unique_by</code>, then <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">value</code> can be <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">email</code> or <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">id</code>.</p> </li> <li class="text-base leading-relaxed"> <p class="mb-2">When <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">type</code> is <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">max_redemptions</code>, then <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">value</code> can be any integer in the range <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">1</code> <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">coupon.max_redemptions</code>, inclusive.</p> </li> <li class="text-base leading-relaxed"> <p class="mb-2">When type is <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">new_customer</code> or <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">existing_customer</code> then <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">value</code> can be <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">based_on_invoice</code>.</p> </li> </ul>

<div class="api-description"><h2>Overview</h2><p class="mb-2">Coupons are deductions applied to invoices or invoice line items. They&#x27;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.</p><div class="alert alert-info"><p class="mb-2"><strong class="font-semibold">Note:</strong></p><p class="mb-2">If you wish to provide discounts to your customers via API or the Chargebee app, see <a href="/docs/api/discounts">Discounts API</a></p></div><h2>Order of application of coupons and discounts</h2><p class="mb-2">When both <a href="/docs/api/coupons">coupons</a> and <a href="/docs/api/discounts">discounts</a> are applied simultaneously to a <a href="/docs/api/subscriptions">subscription</a> or <a href="/docs/api/invoices/create-invoice-for-items-and-one-time-charges">one-time invoice</a>, they&#x27;re applied in the following order:</p><div class="relative w-full overflow-x-auto"><table class="cb-table" border="2"><tbody><tr><td class="ak-renderer-table-number-column"></td><th class="ak-renderer-tableHeader-sortable-column" colSpan="1" rowspan="1"><strong class="font-semibold">Summary</strong></th><th class="ak-renderer-tableHeader-sortable-column" colSpan="1" rowspan="1"><strong class="font-semibold">Description</strong></th></tr><tr><td class="ak-renderer-table-number-column">1</td><td colSpan="1" rowspan="1">Line-level, fixed amount coupons</td><td colSpan="1" rowspan="1"><code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">coupon</code> with <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">apply_on</code> = <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">each_specified_item</code> and <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">discount_type</code> = <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">flat</code></td></tr><tr><td class="ak-renderer-table-number-column">2</td><td colSpan="1" rowspan="1">Line-level, fixed amount discounts</td><td colSpan="1" rowspan="1"><code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">discount</code> with <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">apply_on</code> = <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">specific_item_price</code> and <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">type</code> = <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">fixed_amount</code></td></tr><tr><td class="ak-renderer-table-number-column">3</td><td colSpan="1" rowspan="1">Line-level, percentage coupons</td><td colSpan="1" rowspan="1"><code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">coupon</code> with <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">apply_on</code> = <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">each_specified_item</code> and <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">discount_type</code> = <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">percentage</code></td></tr><tr><td class="ak-renderer-table-number-column">4</td><td colSpan="1" rowspan="1">Line-level, percentage discounts</td><td colSpan="1" rowspan="1"><code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">discount</code> with <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">apply_on</code> = <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">specific_item_price</code> and <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">type</code> = <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">percentage</code></td></tr><tr><td class="ak-renderer-table-number-column">5</td><td colSpan="1" rowspan="1">Invoice-level, fixed amount coupons</td><td colSpan="1" rowspan="1"><code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">coupon</code> with <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">apply_on</code> = <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">invoice_amount</code> and <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">discount_type</code> = <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">flat</code></td></tr><tr><td class="ak-renderer-table-number-column">6</td><td colSpan="1" rowspan="1">Invoice-level, fixed amount discounts</td><td colSpan="1" rowspan="1"><code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">discount</code> with <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">apply_on</code> = <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">invoice_amount</code> and <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">type</code> = <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">fixed_amount</code></td></tr><tr><td class="ak-renderer-table-number-column">7</td><td colSpan="1" rowspan="1">Invoice-level, percentage coupons</td><td colSpan="1" rowspan="1"><code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">coupon</code> with <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">apply_on</code> = <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">invoice_amount</code> and <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">discount_type</code> = <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">percentage</code></td></tr><tr><td class="ak-renderer-table-number-column">8</td><td colSpan="1" rowspan="1">Invoice-level, percentage discounts</td><td colSpan="1" rowspan="1"><code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">discount</code> with <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">apply_on</code> = <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">invoice_amount</code> and <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">type</code> = <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">percentage</code></td></tr></tbody></table></div><p class="mb-2">For example, consider the following scenario:</p><p class="mb-2">A subscription is created with:</p><ul class="list-disc list-outside ml-6 my-4 space-y-2"> <li class="text-base leading-relaxed">a plan price of $200 per month</li> <li class="text-base leading-relaxed">an addon price of $20 per month</li> <li class="text-base leading-relaxed">a flat $5 invoice discount</li> <li class="text-base leading-relaxed">a 1% off coupon on the addon</li> <li class="text-base leading-relaxed">a flat $2 coupon on the invoice</li> </ul><p class="mb-2">The above coupons and discount are applied in the following order:</p><div class="relative w-full overflow-x-auto"><table class="cb-table" border="2"><tbody><tr><td class="ak-renderer-table-number-column"></td><th class="ak-renderer-tableHeader-sortable-column" colSpan="1" rowspan="1"><strong class="font-semibold">Discount or coupon applied</strong></th><th class="ak-renderer-tableHeader-sortable-column" colSpan="1" rowspan="1"><strong class="font-semibold">Subtotal at each step</strong></th></tr><tr><td class="ak-renderer-table-number-column">1</td><td colSpan="1" rowspan="1">Initial subtotal (plan price + addon price)</td><td colSpan="1" rowspan="1">$200 + $20 = $220</td></tr><tr><td class="ak-renderer-table-number-column">2</td><td colSpan="1" rowspan="1">1% off coupon on the addon</td><td colSpan="1" rowspan="1">$200 + $(20 - 0.02) = $200 + $19.98 = $219.98</td></tr><tr><td class="ak-renderer-table-number-column">3</td><td colSpan="1" rowspan="1">Flat $2 coupon on the invoice</td><td colSpan="1" rowspan="1">$219.98 - $2 = $217.98</td></tr><tr><td class="ak-renderer-table-number-column">4</td><td colSpan="1" rowspan="1">Flat $5 invoice discount</td><td colSpan="1" rowspan="1">$217.98 - $5 = <strong class="font-semibold">$212.98</strong></td></tr></tbody></table></div></div>

<p class="mb-2">Used to uniquely identify the coupon in your website/application and to integrate with Chargebee.</p> <div class="alert alert-info"><p class="mb-2"><strong class="font-semibold">Note:</strong></p><p class="mb-2">When the coupon ID contains a special character; for example: <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">#</code>, the API returns an error. Make sure that you <a href="https://www.urlencoder.org/">encode</a> the coupon ID in the path parameter before making an API call.</p></div>

<p class="mb-2">The display name used in web interface for identifying the coupon.</p> <div class="alert alert-info"><p class="mb-2"><strong class="font-semibold">Note:</strong></p><p class="mb-2">When the name of the coupon set contains a special character; for example: <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">#</code>, the API returns an error. Make sure that you <a href="https://www.urlencoder.org/">encode</a> the name of the coupon set in the path parameter before making an API call.</p></div>

Display name used in invoice. If it is not configured then name is used in invoice.

<p class="mb-2">Specifies the type of discount to be applied.</p> * percentage - <p class="mb-2">A percentage of the original price is deducted as a discount. The discount percentage is specified in <code><a href="/docs/api/coupons/coupon-object#discount_percentage">discount_percentage</a></code>.</p> <div class="alert alert-info"><p class="mb-2"><a href="https://www.chargebee.com/docs/2.0/coupons.html#percentage-coupons">Learn more</a> about <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">percentage</code> coupons.</p></div> * fixed_amount - <p class="mb-2">A fixed amount is deducted as a discount. The discount amount is specified in <code><a href="/docs/api/coupons/coupon-object#discount_amount">discount_amount</a></code>.</p> <div class="alert alert-info"><p class="mb-2"><a href="https://www.chargebee.com/docs/2.0/coupons.html#fixed-amount-coupons">Learn more</a> about <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">fixed_amount</code> coupons.</p></div> * offer_quantity - <p class="mb-2">A specified number of units of the item price are offered for free. The number of free units is specified in <code><a href="/docs/api/coupons/coupon-object#discount_quantity">discount_quantity</a></code>. The <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">offer_quantity</code> option is valid only when <code><a href="/docs/api/coupons/coupon-object#apply_on">apply_on</a></code> is set to <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">each_specified_item</code> and the <code><a href="/docs/api/item_prices/item_price-object#pricing_model">pricing_model</a></code> of the item price is <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">per_unit</code>.</p> <div class="alert alert-info"><p class="mb-2"><a href="https://www.chargebee.com/docs/2.0/coupons.html#offer-quantity-coupons">Learn more</a> about <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">offer_quantity</code> coupons.</p></div>

One offixed_amountpercentageoffer_quantityDefault "percentage"

The percentage of the original amount that should be deducted from it.

The value of the deduction. The format of this value depends on the [kind of currency](/docs/api/currencies) .

<p class="mb-2">Specifies the number of free units provided for the <a href="/docs/api/item_prices">item price</a> , without affecting the total quantity sold. This parameter is applicable only when the <code><a href="/docs/api/coupons/coupon-object#discount_type">discount_type</a></code> is set to <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">offer_quantity</code> .</p>

The currency code ([ISO 4217 format](https://www.chargebee.com/docs/supported-currencies.html) ) of the coupon. Applicable for *fixed_amount* coupons alone.

<p class="mb-2">Specifies the time duration for which this coupon is attached to the subscription.</p> * forever - <p class="mb-2">The coupon is attached to the subscription and applied on the invoices until explicitly removed.</p> * one_time - <p class="mb-2">The coupon stays attached to the subscription till it is applied on an invoice <strong class="font-semibold">once</strong>. It is removed after that from the subscription.</p> * limited_period - <p class="mb-2">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 <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">period</code> and <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">period_unit</code> .</p>

One ofone_timeforeverlimited_periodDefault "forever"

The date from which the coupon can be applied to subscriptions.

Date upto which the coupon can be applied to new subscriptions.

Maximum number of times this coupon can be redeemed. **Note:** If not specified, the coupon can be redeemed an indefinite number of times.

<p class="mb-2">Status of the coupon.</p> * future - <p class="mb-2">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.</p> * expired - <p class="mb-2">Cannot be applied to a subscription. A coupon may expire due to exceeding <code><a href="/docs/api/coupons/coupon-object#max_redemptions">max_redemptions</a></code> or <code><a href="/docs/api/coupons/coupon-object#valid_till">valid_till</a></code> date is past. Existing associations remain unaffected.</p> * archived - <p class="mb-2">Cannot be applied to a subscription. Existing associations remain unaffected.</p> * active - <p class="mb-2">Can be applied to a subscription.</p> * deleted - <p class="mb-2">Indicates the coupon has been deleted.</p>

One ofactiveexpiredarchiveddeletedfutureDefault "active"

<p class="mb-2">The amount on the invoice to which the coupon is applied.</p> * invoice_amount - <p class="mb-2">The coupon is applied to the invoice <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">sub_total</code> .</p> * each_specified_item - <p class="mb-2">Applies the coupon to specified items (plans, addons, or charges), with the discount applied to each matching <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">invoice.line_item.amount</code>.</p> <p class="mb-2">Requires applicability to be configured using <a href="/docs/api/coupons/coupon-object#item_constraints" class="text-blue-600 hover:text-blue-800 underline"><code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">item_constraints</code></a>—for example <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">all</code>, <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">criteria</code>, or <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">specific</code> with <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">item_price_ids</code>.</p> <p class="mb-2">When you attach this coupon to a subscription, at least one of that subscription&#x27;s plans, addons, or charges must match those rules. If none do, the request fails.</p>

One ofinvoice_amounteach_specified_item

Timestamp indicating when this coupon is created.

Timestamp indicating when this coupon was archived.

<p class="mb-2">The version number of this resource. For every change made to the resource, <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">resource_version</code> is updated with a new timestamp in milliseconds.</p>

<p class="mb-2">Timestamp indicating when this coupon was last updated. Note that this does not change when the <code><a href="/docs/api/coupons/coupon-object#redemptions">redemptions</a></code> attribute is changed. This attribute will be present only if the resource has been updated after 2016-11-09.</p>

<p class="mb-2">The duration of time for which the coupon is attached to the subscription, in <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">period_units</code>. Applicable only when <code><a href="/docs/api/coupons/coupon-object#duration_type">duration_type</a></code> is <code><a href="/docs/api/coupons/coupon-object#duration_type">limited_period</a></code> .</p>

<p class="mb-2">The unit of time for period. Applicable only when <code><a href="/docs/api/coupons/coupon-object#duration_type">duration_type</a></code> is <code><a href="/docs/api/coupons/coupon-object#duration_type">limited_period</a></code> .</p> * month - <p class="mb-2">A period of 1 calendar month.</p> * week - <p class="mb-2">A period of 7 days.</p> * year - <p class="mb-2">A period of 1 calendar year.</p> * day - <p class="mb-2">A period of 24 hours.</p>

One ofdayweekmonthyear

The number of times this coupon has been redeemed.

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.

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

Indicates whether the coupon has been deleted or not.

The list of item constraints.

The list of item constraint criteria.

List of constraints applicable on the redemption of this coupon.