List coupons

Important
For sites where both legacy and latest product catalog versions are active, GET API requests return responses in a compat format by default. This format works with both latest and legacy Product Catalog.

Override options:

chargebee-response-schema-type: items → Return response in latest product catalog format only.
chargebee-response-schema-type: plans_addons → Return response in legacy product catalog format only.

List all the available coupons that are created for a specific promotion or offers. You can find list of coupon codes that are currently active, expired, archived or deleted.

Sample Request

Sample Result[JSON]

URL Format

GET https://[site].chargebee.com/api/v2/coupons

Input Parameters

limit

optional, integer, default=10, min=1, max=100

The number of resources to be returned.

offset

optional, string, max chars=1000

Determines your position in the list for pagination. To ensure that the next page is retrieved correctly, always set offset to the value of next_offset obtained in the previous iteration of the API call.

sort_by[<sort-order>]

optional, object

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.

Filter Params

For operator usages, see the Pagination and Filtering section.

id[<operator>]

optional, string filter

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 the coupon ID in the path parameter before making an API call.

. Supported operators : is, is_not, starts_with, in, not_in

Example → id[is] = "OFF2008"

Supported operators: is, is_not, starts_with, in, not_in

Example → OFF2008

name[<operator>]

optional, string filter

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 the name of the coupon set in the path parameter before making an API call.

. Supported operators : is, is_not, starts_with, in, not_in

Example → name[is] = "Offer 10"

Supported operators: is, is_not, starts_with, in, not_in

Example → Offer 10

discount_type[<operator>]

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"

Supported operators: is, is_not, in, not_in

Example → fixed_amount

duration_type[<operator>]

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"

Supported operators: is, is_not, in, not_in

Example → forever

status[<operator>]

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] = "active"

Supported operators: is, is_not, in, not_in

Example → active

apply_on[<operator>]

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"

Supported operators: is, is_not, in, not_in

Example → invoice_amount

created_at[<operator>]

optional, timestamp(UTC) in seconds filter

Timestamp indicating when this coupon is created. Supported operators : after, before, on, between

Example → created_at[after] = "145222875"

Supported operators: after, before, on, between

Example → 145222875

updated_at[<operator>]

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[after] = "1243545465"

Supported operators: after, before, on, between

Example → 1243545465

currency_code[<operator>]

optional, string filter

The currency code (ISO 4217 format ) of the coupon. Applicable for fixed_amount coupons alone. Supported operators : is, is_not, starts_with, in, not_in

Example → currency_code[is] = "USD"

Supported operators: is, is_not, starts_with, in, not_in

Example → USD

applicable_item_price_ids[<operator>]

Supported operators: is, in

Example → day-pass-USD

Returns

next_offset

optional, string, max chars=1000

This attribute is returned only if more resources are present. To fetch the next set of resources use this value for the input parameter offset.

coupon

Coupon object

Resource object representing coupon