List Coupons

List coupons

GET/coupons

Use it in a workflow

Add a step and choose the Chargebee connector.
Pick the List Coupons action (under Chargebee API).
Fill in the fields below, then reference the result from later steps as {{listCoupons.response.data}}.

Request

Query parameters

limitinteger (int32)

The number of resources to be returned.

Default 10

offsetstring

<p class="mb-2">Determines your position in the list for pagination. To ensure that the next page is retrieved correctly, always set <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">offset</code> to 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">next_offset</code> obtained in the previous iteration of the API call.</p>

idobject

<dfn class="text-muted"><p class="mb-2">optional, string filter</p></dfn> <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">. <strong class="font-semibold">Supported operators :</strong> is, is_not, starts_with, in, not_in</p> <p class="mb-2"><strong class="font-semibold">Example →</strong> <em class="italic">id[is] = "OFF2008"</em></p>

isstring

is_notstring

starts_withstring

instring

not_instring

nameobject

<dfn class="text-muted"><p class="mb-2">optional, string filter</p></dfn> <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">. <strong class="font-semibold">Supported operators :</strong> is, is_not, starts_with, in, not_in</p> <p class="mb-2"><strong class="font-semibold">Example →</strong> <em class="italic">name[is_not] = "Offer 10"</em></p>

isstring

is_notstring

starts_withstring

instring

not_instring

discount_typeobject

optional, enumerated string filter The type of deduction. Possible values are : fixed_amount, percentage. **Supported operators :** is, is_not, in, not_in **Example →** *discount_type\[is\] = "fixed_amount"*

isstring

\* \`fixed_amount\` - The specified amount will be deducted. \* \`percentage\` - The specified percentage will be deducted. \* \`offer_quantity\` - The specified units will be offered without any deduction.

One offixed_amountpercentageoffer_quantity

is_notstring

One offixed_amountpercentageoffer_quantity

instring

One offixed_amountpercentageoffer_quantity

not_instring

One offixed_amountpercentageoffer_quantity

duration_typeobject

optional, enumerated string filter Specifies the time duration for which this coupon is attached to the subscription. Possible values are : one_time, forever, limited_period. **Supported operators :** is, is_not, in, not_in **Example →** *duration_type\[is\] = "forever"*

isstring

* `one_time` - The coupon stays attached to the subscription till it is applied on an invoice <b>once</b>. 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 <code>period</code> and <code>period_unit</code>.

One ofone_timeforeverlimited_period

is_notstring

One ofone_timeforeverlimited_period

instring

One ofone_timeforeverlimited_period

not_instring

One ofone_timeforeverlimited_period

statusobject

optional, enumerated string filter Status of the coupon. Possible values are : active, expired, archived, deleted. **Supported operators :** is, is_not, in, not_in **Example →** *status\[is_not\] = "active"*

isstring

* `active` - Can be applied to a subscription. * `expired` - Cannot be applied to a subscription. A coupon may expire due to exceeding <code><a href="/docs/api/coupons?#coupon_max_redemptions">max_redemptions</a></code> or <code><a href="/docs/api/coupons?#coupon_valid_till">valid_till</a></code> 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.

One ofactiveexpiredarchiveddeletedfuture

is_notstring

One ofactiveexpiredarchiveddeletedfuture

instring

One ofactiveexpiredarchiveddeletedfuture

not_instring

One ofactiveexpiredarchiveddeletedfuture

apply_onobject

optional, enumerated string filter The amount on the invoice to which the coupon is applied. Possible values are : invoice_amount, each_specified_item. **Supported operators :** is, is_not, in, not_in **Example →** *apply_on\[is\] = "invoice_amount"*

isstring

* `invoice_amount` - The coupon is applied to the invoice <code>sub_total</code>. * `specified_items_total` - **(Deprecated)** Discount will be applied to the total of plan and addon items specified. * `each_specified_item` - <div prod_cat_ver="2"> The coupon is applied to the <code>invoice.line_item.amount</code> that corresponds to the item price specified by <code>item_price_id</code>. </div> <div prod_cat_ver="1"> The coupon is applied to the <code>invoice.line_item.amount</code> that corresponds to the plan or addon specified by <code>plan_ids</code> and <code>addon_ids</code>. </div> * `each_unit_of_specified_items` - **(Deprecated)** Discount will be applied to each unit of plan and addon items specified.

One ofinvoice_amounteach_specified_item

is_notstring

One ofinvoice_amounteach_specified_item

instring

One ofinvoice_amounteach_specified_item

not_instring

One ofinvoice_amounteach_specified_item

created_atobject

optional, timestamp(UTC) in seconds filter Timestamp indicating when this coupon is created. **Supported operators :** after, before, on, between **Example →** *created_at\[before\] = "145222875"*

afterstring (unix-time)

beforestring (unix-time)

onstring (unix-time)

betweenstring

updated_atobject

optional, timestamp(UTC) in seconds filter To filter based on updated at. This attribute will be present only if the resource has been updated after 2016-11-09. **Supported operators :** after, before, on, between **Example →** *updated_at\[on\] = "1243545465"*

afterstring (unix-time)

beforestring (unix-time)

onstring (unix-time)

betweenstring

sort_byobject

optional, string filter Sorts based on the specified attribute. **Supported attributes :** created_at **Supported sort-orders :** asc, desc **Example →** *sort_by\[asc\] = "created_at"* This will sort the result based on the 'created_at' attribute in ascending(earliest first) order.

ascstring

One ofcreated_at

descstring

One ofcreated_at

currency_codeobject

optional, string filter The currency code ([ISO 4217 format](https://www.chargebee.com/docs/supported-currencies.html) ) of the coupon. Applicable for *fixed_amount* coupons alone. **Supported operators :** is, is_not, starts_with, in, not_in **Example →** *currency_code\[is\] = "USD"*

isstring

is_notstring

starts_withstring

instring

not_instring

applicable_item_price_idsobject

optional, string filter List of itemPrice ids for which these coupons are applicable. **Supported operators :** in, is **Example →** *applicable_item_price_ids\[is\] = "day-pass-USD"*

instring

isstring

Headers

chargebee-request-origin-devicestring

The device from which the customer has made the request

chargebee-request-origin-userstring (email)

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

chargebee-request-origin-user-encodedstring (email)

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.

chargebee-request-origin-ipstring

The IP address of the customer where the request originated

chargebee-business-entity-idstring

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.

Response

Returns 200 with an object. Read it in later steps with {{listCoupons.response.data.<field>}}.

listarray<object>

couponobjectrequired27 fields

<div class="api-description"><h2>Overview</h2><p class="mb-2">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.</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'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>

next_offsetstring

<p class="mb-2">This attribute is returned only if more resources are present. To fetch the next set of resources use this value for the input parameter <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">offset</code>.</p>

json

{
  "list": null,
  "next_offset": null
}

Need more? See the Chargebee guide for connection setup and behaviour shared by every action.

Was this page helpful?