Coupons

API Version

Product Catalog

Library

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

Order of application of coupons and discounts

When both coupons and discounts are applied simultaneously to a subscription or one-time 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, 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"
        },
        {
            "constraint": "none",
            "item_type": "addon"
        },
        {
            "constraint": "none",
            "item_type": "charge"
        }
    ],
    "name": "Summer Offer",
    "object": "coupon",
    "redemptions": 0,
    "resource_version": 1517495314967,
    "status": "active",
    "updated_at": 1517495314
}

API Index URL

https://{site}.chargebee.com/api/v2/coupons

id

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

name

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

enumerated string, default=percentage

Specifies the type of discount to be applied.

Possible values are

discount_percentage

optional, double, min=0.01, max=100.0

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 .

discount_quantity

optional, integer, min=1

Specifies the number of free units provided for the item price , without affecting the total quantity sold. This parameter is applicable only when the discount_type is set to offer_quantity .

currency_code

optional, string, max chars=3

The currency code (ISO 4217 format ) of the coupon. Applicable for fixed_amount coupons alone.

duration_type

enumerated string, default=forever

Specifies the time duration for which this coupon is attached to the subscription.

Possible values are

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 values are

apply_on

enumerated string

The amount on the invoice to which the coupon is applied.

Possible values are

created_at

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 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 is limited_period .

period_unit

optional, enumerated string

The unit of time for period. Applicable only when duration_type is limited_period .

Possible values are

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

deleted

boolean

Indicates whether the coupon has been deleted or not.

item_constraints
Show attributes [+]

optional, list of item_constraint

The list of item constraints.

item_constraint_criteria
Show attributes [+]

optional, list of item_constraint_criteria

The list of item constraint criteria.

coupon_constraints
Show attributes [+]

optional, list of coupon_constraint

List of constraints applicable on the redemption of this coupon.

Coupon constraint attributes

entity_type

enumerated string

The resource type for the constraint. This, along with type and value , helps define the specific rule applied.

Possible values are

type

enumerated string

Type of coupon constraints

Possible values are

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.

id

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

name

string, max chars=50

The display name used in web interface for identifying the coupon.

Note:

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

enumerated string, default=percentage

Specifies the type of discount to be applied.

Possible values are

discount_percentage

optional, double, min=0.01, max=100.0

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 .

discount_quantity

optional, integer, min=1

Specifies the number of free units provided for the item price , without affecting the total quantity sold. This parameter is applicable only when the discount_type is set to offer_quantity .

currency_code

optional, string, max chars=3

The currency code (ISO 4217 format ) of the coupon. Applicable for fixed_amount coupons alone.

duration_type

enumerated string, default=forever

Specifies the time duration for which this coupon is attached to the subscription.

Possible values are

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 values are

apply_on

enumerated string

The amount on the invoice to which the coupon is applied.

Possible values are

created_at

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

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 is limited_period .

period_unit

optional, enumerated string

The unit of time for period. Applicable only when duration_type is limited_period .

Possible values are

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

deleted

boolean

Indicates whether the coupon has been deleted or not.

item_constraints

optional, list of item_constraint

The list of item constraints.

item_constraint_criteria

optional, list of item_constraint_criteria

The list of item constraint criteria.

coupon_constraints

optional, list of coupon_constraint

List of constraints applicable on the redemption of this coupon.

Try in API Explorer

This API creates a new coupon for a specific promotion or offers.

Sample Request

Try in API Explorer

Only for Java

Only for Java

copy full code

Click to Copy

curl  https://{site}.chargebee.com/api/v2/coupons/create_for_items \
     -u {site_api_key}:\
     -d id="summer_offer" \
     -d name="Summer Offer" \
     -d discount_percentage=10 \
     -d discount_type="PERCENTAGE" \
     -d duration_type="FOREVER" \
     -d apply_on="EACH_SPECIFIED_ITEM" \
     -d "item_constraints[constraint][0]"="ALL" \
     -d "item_constraints[item_type][0]"="PLAN"

curl  https://{site}.chargebee.com/api/v2/coupons/create_for_items \
     -u {site_api_key}:\
     -d id="welcome_offer" \
     -d name="Welcome Offer" \
     -d discount_percentage=15 \
     -d discount_type="PERCENTAGE" \
     -d duration_type="ONE_TIME" \
     -d apply_on="INVOICE_AMOUNT" \
     -d "coupon_constraints[entity_type][0]"="CUSTOMER" \
     -d "coupon_constraints[type][0]"="NEW_CUSTOMER" \
     -d "coupon_constraints[value][0]"="based_on_invoice"

copy

Click to Copy

Create a coupon for items with constraints

200:

STATUS

Sample Response [ JSON ]

{
    "coupon": {
        "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
    }
}

URL Format POST

https://{site}.chargebee.com/api/v2/coupons/create_for_items

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

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[]

optional, enumerated string, default=percentage

Specifies the type of discount to be applied.

Possible values are

discount_amount[]

optional, in cents, min=0

The value of the deduction. The format of this value depends on the kind of currency .

currency_code[]

required if Multicurrency is enabled, string, max chars=3

The currency code (ISO 4217 format ) of the coupon. Applicable for fixed_amount coupons alone.

discount_percentage[]

optional, double, min=0.01, max=100.0

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

discount_quantity[]

optional, integer, min=1

Specifies the number of free units provided for the item price , without affecting the total quantity sold. This parameter is applicable only when the discount_type is set to offer_quantity .

apply_on[]

required, enumerated string

The amount on the invoice to which the coupon is applied.

Possible values are

duration_type[]

optional, enumerated string, default=forever

Specifies the time duration for which this coupon is attached to the subscription.

Possible values are

duration_month[]

optional, integer, min=1, max=240

(Deprecated) The duration of time in months for which the coupon is attached to the subscription. Applicable only when duration_type is limited_period.

Note: This parameter has been deprecated. Use period and period_unit instead.

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.

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

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 is limited_period .

period_unit[]

optional, enumerated string

The unit of time for period. Applicable only when duration_type is limited_period .

Possible values are

status[]

optional, enumerated string, default=active

Status of the coupon.

Possible values are

item_constraints

Parameters for item_constraints. Multiple item_constraints can be passed by specifying unique indices.
pass parameters as item_constraints[<param name>][<idx:0..n>]

item_constraints[constraint][0..n]

required, enumerated string

Possible values are

item_constraints[item_type][0..n]

required, enumerated string

Possible values are

item_constraints[item_price_ids][0..n]

optional

item_constraint_criteria

Parameters for item_constraint_criteria. Multiple item_constraint_criteria can be passed by specifying unique indices.
pass parameters as item_constraint_criteria[<param name>][<idx:0..n>]

item_constraint_criteria[item_type][0..n]

optional, enumerated string

Possible values are

item_constraint_criteria[item_family_ids][0..n]

optional

item_constraint_criteria[currencies][0..n]

optional

item_constraint_criteria[item_price_periods][0..n]

optional

coupon_constraints

Parameters for coupon_constraints. Multiple coupon_constraints can be passed by specifying unique indices.
pass parameters as coupon_constraints[<param name>][<idx:0..n>]

coupon_constraints[entity_type][0..n]

required, enumerated string

Possible values are

coupon_constraints[type][0..n]

required, enumerated string

Possible values are

coupon_constraints[value][0..n]

optional, string, max chars=65k

coupon

always returned
Resource object representing coupon

Try in API Explorer

This API updates a coupon that is created for a specific promotion or offers.

Sample Request

Try in API Explorer

Only for Java

Only for Java

copy full code

Click to Copy

curl  https://{site}.chargebee.com/api/v2/coupons/sample_coupon/update_for_items \
     -X POST  \
     -u {site_api_key}:\
     -d discount_percentage=20 \
     -d "item_constraints[constraint][0]"="ALL" \
     -d "item_constraints[item_type][0]"="PLAN" \
     -d "item_constraints[constraint][1]"="ALL" \
     -d "item_constraints[item_type][1]"="ADDON"

curl  https://{site}.chargebee.com/api/v2/coupons/welcome_offer/update_for_items \
     -X POST  \
     -u {site_api_key}:\
     -d name="return_offer" \
     -d discount_percentage=25 \
     -d "coupon_constraints[entity_type][0]"="CUSTOMER" \
     -d "coupon_constraints[type][0]"="EXISTING_CUSTOMER" \
     -d "coupon_constraints[value][0]"="based_on_invoice"

copy

Click to Copy

Update a coupon for items with constraints

200:

STATUS

Sample Response [ JSON ]

{
    "coupon": {
        "apply_discount_on": "not_applicable",
        "apply_on": "each_specified_item",
        "created_at": 1517495316,
        "discount_percentage": 20,
        "discount_type": "percentage",
        "duration_type": "forever",
        "id": "sample_coupon",
        "item_constraints": [
            {
                "constraint": "all",
                "item_type": "plan"
            },
            {..}
        ],
        "name": "Sample Coupon",
        "object": "coupon",
        "redemptions": 0,
        "resource_version": 1517495317068,
        "status": "active",
        "updated_at": 1517495317
    }
}

URL Format POST

https://{site}.chargebee.com/api/v2/coupons/{coupon-id}/update_for_items

name[]

optional, string, max chars=50

The display name used in web interface for identifying the coupon.

Note:

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[]

optional, enumerated string, default=percentage

Specifies the type of discount to be applied.

Possible values are

discount_amount[]

optional, in cents, min=0

The value of the deduction. The format of this value depends on the kind of currency .

currency_code[]

required if Multicurrency is enabled, string, max chars=3

The currency code (ISO 4217 format ) of the coupon. Applicable for fixed_amount coupons alone.

discount_percentage[]

optional, double, min=0.01, max=100.0

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

discount_quantity[]

optional, integer, min=1

Specifies the number of free units provided for the item price , without affecting the total quantity sold. This parameter is applicable only when the discount_type is set to offer_quantity .

apply_on[]

optional, enumerated string

The amount on the invoice to which the coupon is applied.

Possible values are

duration_type[]

optional, enumerated string, default=forever

Specifies the time duration for which this coupon is attached to the subscription.

Possible values are

duration_month[]

optional, integer, min=1, max=240

(Deprecated) The duration of time in months for which the coupon is attached to the subscription. Applicable only when duration_type is limited_period.

Note: This parameter has been deprecated. Use period and period_unit instead.

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.

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

included_in_mrr[]

optional, boolean

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 is limited_period .

period_unit[]

optional, enumerated string

The unit of time for period. Applicable only when duration_type is limited_period .

Possible values are

item_constraints

Parameters for item_constraints. Multiple item_constraints can be passed by specifying unique indices.
pass parameters as item_constraints[<param name>][<idx:0..n>]

item_constraints[constraint][0..n]

required, enumerated string

Possible values are

item_constraints[item_type][0..n]

required, enumerated string

Possible values are

item_constraints[item_price_ids][0..n]

optional

item_constraint_criteria

Parameters for item_constraint_criteria. Multiple item_constraint_criteria can be passed by specifying unique indices.
pass parameters as item_constraint_criteria[<param name>][<idx:0..n>]

item_constraint_criteria[item_type][0..n]

optional, enumerated string

Possible values are

item_constraint_criteria[item_family_ids][0..n]

optional

item_constraint_criteria[currencies][0..n]

optional

item_constraint_criteria[item_price_periods][0..n]

optional

coupon_constraints

Parameters for coupon_constraints. Multiple coupon_constraints can be passed by specifying unique indices.
pass parameters as coupon_constraints[<param name>][<idx:0..n>]

coupon_constraints[entity_type][0..n]

required, enumerated string

Possible values are

coupon_constraints[type][0..n]

required, enumerated string

Possible values are

coupon_constraints[value][0..n]

optional, string, max chars=65k

coupon

always returned
Resource object representing coupon

Try in API Explorer

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

Try in API Explorer

Only for Java

copy full code

Click to Copy

curl  https://{site}.chargebee.com/api/v2/coupons \
     -G  \
     -u {site_api_key}:\
     --data-urlencode limit=5 \
     --data-urlencode "duration_type[is]"="forever" \
     --data-urlencode "status[is]"="active" \
     --data-urlencode "sort_by[asc]"=created_at

copy

Click to Copy

200:

STATUS

Sample Response [ JSON ]

{
    "list": [
        {
            "coupon": {
                "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
            }
        },
        {..}
    ]
}

URL Format GET

https://{site}.chargebee.com/api/v2/coupons

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, 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 → id[is] = "OFF2008"

name[<operator>]

optional, string filter

The display name used in web interface for identifying the coupon.

Note:

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

Example → name[is_not] = "Offer 10"

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

Example → name[is] = "Offer 10"

discount_type[<operator>]

optional, enumerated string filter

The type of deduction. Possible values are : fixed_amount, percentage, offer_quantity
Supported operators : is, is_not, in, not_in

Example → discount_type[is] = "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"

status[<operator>]

optional, enumerated string filter

Status of the coupon. Possible values are : active, expired, archived, deleted, future
Supported operators : is, is_not, in, not_in

Example → status[is] = "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"

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[before] = "145222875"

Supported operators : after, before, on, between

Example → created_at[after] = "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[on] = "1243545465"

Supported operators : after, before, on, between

Example → updated_at[after] = "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 → currency_code[is] = "USD"

coupon

always returned
Resource object representing coupon

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

Try in API Explorer

This API retrieves a specific coupon using the coupon ID.

Sample Request

Try in API Explorer

Only for Java

copy full code

Click to Copy

curl  https://{site}.chargebee.com/api/v2/coupons/demo_offer \
     -u {site_api_key}:

copy

Click to Copy

200:

STATUS

Sample Response [ JSON ]

{
    "coupon": {
        "apply_discount_on": "not_applicable",
        "apply_on": "each_specified_item",
        "created_at": 1517495364,
        "currency_code": "USD",
        "discount_amount": 500,
        "discount_type": "fixed_amount",
        "duration_type": "forever",
        "id": "demo_offer",
        "item_constraints": [
            {
                "constraint": "all",
                "item_type": "plan"
            },
            {..}
        ],
        "name": "Demo Offer",
        "object": "coupon",
        "redemptions": 0,
        "resource_version": 1517495364521,
        "status": "active",
        "updated_at": 1517495364
    }
}

URL Format GET

https://{site}.chargebee.com/api/v2/coupons/{coupon-id}

coupon

always returned
Resource object representing coupon

Sample admin console URL

https://{site}.chargebee.com/admin-console/coupons/123x

Try in API Explorer

If no Subscriptions/Invoices are linked to this Coupon, the Coupon will be deleted from your Chargebee site. This action cannot be undone.

To ensure that existing Subscriptions/Invoices are not affected, Coupons associated with them will not be deleted, but moved to "Archived" state. Once a Coupon has been archived, it cannot be edited or used again unless unarchived. Unused Coupons codes are deleted.

Sample Request

Try in API Explorer

Only for Java

copy full code

Click to Copy

curl  https://{site}.chargebee.com/api/v2/coupons/beta/delete \
     -X POST  \
     -u {site_api_key}:

copy

Click to Copy

200:

STATUS

Sample Response [ JSON ]

{
    "coupon": {
        "apply_discount_on": "not_applicable",
        "apply_on": "invoice_amount",
        "created_at": 1517495315,
        "currency_code": "USD",
        "discount_amount": 500,
        "discount_type": "fixed_amount",
        "duration_type": "forever",
        "id": "beta",
        "name": "Beta",
        "object": "coupon",
        "redemptions": 0,
        "resource_version": 1612967315122,
        "status": "deleted",
        "updated_at": 1612967315
    }
}

URL Format POST

https://{site}.chargebee.com/api/v2/coupons/{coupon-id}/delete

coupon

always returned
Resource object representing coupon

Try in API Explorer

Copies a coupon over from one site to another. Copying of archived coupons is not supported.

The item prices that are linked to the coupon in the source site are also linked to the coupon in the destination site. However, this will only work if those item prices exist and with the same ids, in the destination site. Hence, it is recommended that the item prices be copied over before copying the coupons.

The value for redemptions is not copied. It is set to 0 for the newly created coupon. Hence, if such a coupon had expired in the source site due to redemptions having reached max_redemptions, it's status would be active in the destination site.

This API is not enabled for live sites by default. Please contact support to get this enabled.

Sample Request

Try in API Explorer

Only for Java

copy full code

Click to Copy

curl  https://{site}.chargebee.com/api/v2/coupons/copy \
     -u {site_api_key}:\
     -d from_site="merchant-test" \
     -d id_at_from_site="copy_coupon"

copy

Click to Copy

200:

STATUS

Sample Response [ JSON ]

{
    "coupon": {
        "apply_discount_on": "not_applicable",
        "apply_on": "each_specified_item",
        "created_at": 1517495314,
        "currency_code": "USD",
        "discount_amount": 100,
        "discount_type": "fixed_amount",
        "duration_type": "one_time",
        "id": "copy_coupon",
        "item_constraints": [
            {
                "constraint": "all",
                "item_type": "plan"
            },
            {..}
        ],
        "name": "Copy Coupon",
        "object": "coupon",
        "redemptions": 0,
        "resource_version": 1517495314819,
        "status": "active",
        "updated_at": 1517495314
    }
}

URL Format POST

https://{site}.chargebee.com/api/v2/coupons/copy

from_site[]

required, string, max chars=50

Your Chargebee site name having the coupon to be copied. Note: Unless you are copying from a twin site (acme & acme-test are twin sites), contact support to have this allow-listed.

id_at_from_site[]

required, string, max chars=100

Id of the coupon to be copied. The new coupon created in this site will have the same Id.

id[]

optional, string, max chars=100

Id of copied coupon in this site.

for_site_merging[]

optional, boolean, default=false

If copy action is performed as part of Chargebee site merge action, pass the value as true. Note: If this parameter is passed true coupon state, redemptions, coupon set and coupon codes associated with this coupon will be copied.

coupon

always returned
Resource object representing coupon

Try in API Explorer

This API unarchives a specific coupon using the coupon ID.

Sample Request

Try in API Explorer

Only for Java

copy full code

Click to Copy

curl  https://{site}.chargebee.com/api/v2/coupons/winter_offer/unarchive \
     -X POST  \
     -u {site_api_key}:

copy

Click to Copy

200:

STATUS

Sample Response [ JSON ]

{
    "coupon": {
        "apply_discount_on": "not_applicable",
        "apply_on": "each_specified_item",
        "created_at": 1517495315,
        "currency_code": "USD",
        "discount_amount": 500,
        "discount_type": "fixed_amount",
        "duration_type": "forever",
        "id": "winter_offer",
        "item_constraints": [
            {
                "constraint": "all",
                "item_type": "plan"
            },
            {..}
        ],
        "name": "Winter Offer",
        "object": "coupon",
        "redemptions": 1,
        "resource_version": 1517495316871,
        "status": "active",
        "updated_at": 1517495316
    }
}

URL Format POST

https://{site}.chargebee.com/api/v2/coupons/{coupon-id}/unarchive

coupon

always returned
Resource object representing coupon

Overview

Order of application of coupons and discounts

Sample coupon [ JSON ]

API Index URL

Model Class

Coupon attributes

Consent Fields for Coupon

Custom Fields for Coupon

Create a coupon for items ¶

Sample Response [ JSON ]

URL Format POST

Method

Input Parameters

Filter Params

For operator usages, see the Pagination and Filtering section.

Returns

Sample admin console URL

Update a coupon for items ¶

Sample Response [ JSON ]

URL Format POST

Method

Input Parameters

Filter Params

For operator usages, see the Pagination and Filtering section.

Returns

Sample admin console URL

List coupons ¶

Sample Response [ JSON ]

URL Format GET

Method

Input Parameters

Filter Params

For operator usages, see the Pagination and Filtering section.

Returns

Sample admin console URL

Retrieve a coupon ¶

Sample Response [ JSON ]

URL Format GET

Method

Input Parameters

Filter Params

For operator usages, see the Pagination and Filtering section.

Returns

Sample admin console URL

Delete a coupon ¶

Sample Response [ JSON ]

URL Format POST

Method

Input Parameters

Filter Params

For operator usages, see the Pagination and Filtering section.

Returns

Sample admin console URL

Copy a coupon ¶

Sample Response [ JSON ]

URL Format POST

Method

Input Parameters

Filter Params

For operator usages, see the Pagination and Filtering section.

Returns

Sample admin console URL

Unarchive a coupon ¶

Sample Response [ JSON ]

URL Format POST

Method

Input Parameters

Filter Params

For operator usages, see the Pagination and Filtering section.

Returns

Sample admin console URL