You are viewing the documentation for the older version of our API (V1). Click here for information on upgrading to the latest version (V2).
    Library
You are viewing the documentation for the older version of our API (V1). Click here for information on upgrading to the latest version (V2).

Coupons

Coupons are discounts codes that you can configure and apply to subscriptions.

Sample coupon [ JSON ]

{ "addon_constraint": "not_applicable", "apply_discount_on": "not_applicable", "apply_on": "invoice_amount", "created_at": 1517498159, "currency_code": "USD", "discount_amount": 500, "discount_type": "fixed_amount", "duration_type": "forever", "id": "sample_offer", "name": "Sample Offer", "object": "coupon", "plan_constraint": "not_applicable", "redemptions": 0, "resource_version": 1517498159000, "status": "active", "updated_at": 1517498159 }

API Index URL GET

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

Coupon attributes

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
The type of deduction
Possible values are
fixed_amountThe specified amount will be deducted.percentageThe specified percentage will be deducted.
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.
duration_type
enumerated string, default=forever
Specifies the time duration for which this coupon is attached to the subscription.
Possible values are
one_timeThe coupon stays attached to the subscription till it is applied on an invoice once. It is removed after that from the subscription.foreverThe coupon is attached to the subscription and applied on the invoices until explicitly removed.limited_periodThe discount is attached to the subscription and applied on the invoices for a limited duration. This duration starts from the point it is applied to an invoice for the first time and expires after a period specified by period and period_unit. .
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_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
activeCan be applied to a subscription.expiredCannot be applied to a subscription. A coupon may expire due to exceeding max_redemptions or valid_till date is past. Existing associations remain unaffected.archivedCannot be applied to a subscription. Existing associations remain unaffected.
apply_on
enumerated string
The amount on the invoice to which the coupon is applied.
Possible values are
invoice_amountThe coupon is applied to the invoice sub_total.each_specified_itemThe coupon is applied to the invoice.line_item.amount that corresponds to the plan or addon specified by plan_ids and addon_ids.
plan_constraint
enumerated string
Plans the coupon can be applied to.
Possible values are
noneCoupon not applicable to any plans.allCoupon applicable to all plans.specificCoupon applicable to specific plan(s).not_applicableCoupon only applicable to invoice amount and not any plans.
addon_constraint
enumerated string
Addons the coupon can be applied to.
Possible values are
noneCoupon not applicable to any addons.allCoupon applicable to all addons.specificCoupon applicable to specific addon(s).not_applicableCoupon only applicable to invoice amount and not any addons.
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.
plan_ids
optional, list of string
List of plan ids for which this coupon is applicable.
addon_ids
optional, list of string
List of addon ids for which this coupon is applicable.
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 set of key-value pairs stored as additional information for the coupon. Learn more.

Create a coupon

Idempotency Supported
This API creates a new coupon for a specific promotion or offers.
Sample Request 
curl  https://{site}.chargebee.com/api/v1/coupons \
     -u {site_api_key}:\
     -d id="sample_offer" \
     -d name="Sample Offer" \
     -d discount_type="fixed_amount" \
     -d discount_amount=500 \
     -d apply_on="invoice_amount" \
     -d duration_type="forever"
copy
curl  https://{site}.chargebee.com/api/v1/coupons \
     -u {site_api_key}:\
     -d id="sample_offer" \
     -d name="Sample Offer" \
     -d discount_type="fixed_amount" \
     -d discount_amount=500 \
     -d apply_on="invoice_amount" \
     -d duration_type="forever"

Sample Response [ JSON ]

Show more...
{"coupon": { "addon_constraint": "not_applicable", "apply_discount_on": "not_applicable", "apply_on": "invoice_amount", "created_at": 1517498159, "currency_code": "USD", "discount_amount": 500, "discount_type": "fixed_amount", "duration_type": "forever", "id": "sample_offer", "name": "Sample Offer", "object": "coupon", "plan_constraint": "not_applicable", "redemptions": 0, "resource_version": 1517498159000, "status": "active", "updated_at": 1517498159 }}

URL Format POST

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

Input Parameters

id
required, string, max chars=100

Used to uniquely identify the coupon in your website/application and to integrate with Chargebee.

Note:

When the coupon ID contains a special character; for example: #, the API returns an error. Make sure that you encode the coupon ID in the path parameter before making an API call.

.
name
required, string, max chars=50

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

Note:

When the name of the coupon set contains a special character; for example: #, the API returns an error. Make sure that you encode 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
optional, enumerated string, default=percentage
The type of deduction.
Possible values are
fixed_amountThe specified amount will be deducted.percentageThe specified percentage will be deducted.
discount_amount
optional, in cents, min=0
The value of the deduction. The format of this value depends on the kind of currency.
discount_percentage
optional, double, min=0.01, max=100.0
The percentage of the original amount that should be deducted from it.
apply_on
required, enumerated string
The amount on the invoice to which the coupon is applied.
Possible values are
invoice_amountThe coupon is applied to the invoice sub_total.each_specified_itemThe coupon is applied to the invoice.line_item.amount that corresponds to the plan or addon specified by plan_ids and addon_ids.
duration_type
optional, enumerated string, default=forever
Specifies the time duration for which this coupon is attached to the subscription.
Possible values are
one_timeThe coupon stays attached to the subscription till it is applied on an invoice once. It is removed after that from the subscription.foreverThe coupon is attached to the subscription and applied on the invoices until explicitly removed.limited_periodThe discount is attached to the subscription and applied on the invoices for a limited duration. This duration starts from the point it is applied to an invoice for the first time and expires after a period specified by period and period_unit.
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_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 set of key-value pairs stored as additional information for the coupon. Learn more.
plan_constraint
optional, enumerated string
Plans the coupon can be applied to.
Possible values are
noneCoupon not applicable to any plans.allCoupon applicable to all plans.specificCoupon only applicable to specified plans. If used, it is mandatory to specify the plan(s).
addon_constraint
optional, enumerated string
Addons the coupon can be applied to.
Possible values are
noneCoupon not applicable to any addons.allCoupon applicable to all addons.specificCoupon only applicable to specified addons. If used, it is mandatory to specify the addon(s).
plan_ids[0..n]
optional, list of string
Identifier of the plan.
addon_ids[0..n]
optional, list of string
Identifier of the addon.

Returns

coupon
always returned
Resource object representing coupon

List coupons

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 
curl  https://{site}.chargebee.com/api/v1/coupons \
     -G  \
     -u {site_api_key}:\
     --data-urlencode limit=5
copy
curl  https://{site}.chargebee.com/api/v1/coupons \
     -G  \
     -u {site_api_key}:\
     --data-urlencode limit=5

Sample Response [ JSON ]

Show more...
{ "list": [ {"coupon": { "addon_constraint": "none", "apply_discount_on": "not_applicable", "apply_on": "each_unit_of_specified_items", "created_at": 1552317358, "discount_amount": 200, "discount_type": "fixed_amount", "duration_type": "forever", "id": "plan_quantity_coupon", "name": "Plan Quantity Coupon", "object": "coupon", "plan_constraint": "all", "redemptions": 0, "status": "active" }}, {..} ], "next_offset": "[\"1517498159000\",\"135000000555\"]" }

URL Format GET

https://{site}.chargebee.com/api/v1/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.

Returns

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

Retrieve a coupon

This API retrieves a specific coupon using the coupon ID.
Sample Request 
curl  https://{site}.chargebee.com/api/v1/coupons/plan_only_coupon \
     -u {site_api_key}:
copy
curl  https://{site}.chargebee.com/api/v1/coupons/plan_only_coupon \
     -u {site_api_key}:

Sample Response [ JSON ]

Show more...
{"coupon": { "addon_constraint": "none", "apply_discount_on": "not_applicable", "apply_on": "each_specified_item", "created_at": 1552317358, "discount_percentage": 10, "discount_type": "percentage", "duration_type": "forever", "id": "plan_only_coupon", "name": "Plan Only Coupon", "object": "coupon", "plan_constraint": "all", "redemptions": 0, "status": "active" }}

URL Format GET

https://{site}.chargebee.com/api/v1/coupons/{coupon_id}

Returns

coupon
always returned
Resource object representing coupon

Sample admin console URL

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