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:
|
|
|
| 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:
|
|
|
| 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 GET
https://{site}.chargebee.com/api/v2/coupons
Model Class
com.chargebee.models.Coupon
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.
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.
optional, string, max chars=100 Display name used in invoice. If it is not configured then name is used in invoice.
enumerated string, default=percentage Specifies the type of discount to be applied. Possible values are
FIXED_AMOUNTA fixed amount is deducted as a discount. The discount amount is specified in discount_amount. PERCENTAGEA percentage of the original price is deducted as a discount. The discount percentage is specified in discount_percentage. OFFER_QUANTITYA specified number of units of the item price are offered for free. The number of free units is specified in discount_quantity. The offer_quantity option is valid only when apply_on is set to each_specified_item and the pricing_model of the item price is per_unit. FIXED_AMOUNTA fixed amount is deducted as a discount. The discount amount is specified in discount_amount. PERCENTAGEA percentage of the original price is deducted as a discount. The discount percentage is specified in discount_percentage. OFFER_QUANTITYA specified number of units of the item price are offered for free. The number of free units is specified in discount_quantity. The offer_quantity option is valid only when apply_on is set to each_specified_item and the pricing_model of the item price is per_unit. Show all values[+]
optional, double, min=0.01, max=100.0 The percentage of the original amount that should be deducted from it.
optional, in cents, min=0 The value of the deduction. The format of this value depends on the kind of currency.
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.
optional, string, max chars=3 The currency code (ISO 4217 format) of the coupon. Applicable for fixed_amount coupons alone.
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.
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.
Show all values[+]
optional, timestamp(UTC) in seconds The date from which the coupon can be applied to subscriptions.
optional, timestamp(UTC) in seconds Date upto which the coupon can be applied to new subscriptions.
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.
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.DELETEDIndicates the coupon has been deleted.FUTUREThe 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. 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.DELETEDIndicates the coupon has been deleted. FUTUREThe 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.
Show all values[+]
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 item price specified by item_price_id.
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 item price specified by item_price_id.
Show all values[+]
timestamp(UTC) in seconds Timestamp indicating when this coupon is created.
optional, timestamp(UTC) in seconds Timestamp indicating when this coupon was archived.
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.
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.
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.
optional, enumerated string The unit of time for period. Applicable only when duration_type is limited_period. Possible values are
DAYA period of 24 hours.WEEKA period of 7 days.MONTHA period of 1 calendar month.YEARA period of 1 calendar year.
DAYA period of 24 hours.WEEKA period of 7 days.MONTHA period of 1 calendar month.YEARA period of 1 calendar year.
Show all values[+]
optional, integer, min=0 The number of times this coupon has been redeemed.
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.
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.
boolean Indicates whether the coupon has been deleted or not. optional, list of item_constraint
The list of item constraints.
ItemConstraint attributes
enumerated string Item type for which this criteria is applicable for. Possible values are
PLANPlanADDONAddonCHARGECharge
enumerated string Constraint applicable for the item Possible values are
NONECoupon not applicable to any items.ALLCoupon applicable to all items.SPECIFICCoupon applicable to specific items.CRITERIACoupon applicable based on criteria.
NONECoupon not applicable to any items.ALLCoupon applicable to all items.SPECIFICCoupon applicable to specific items.CRITERIACoupon applicable based on criteria.
Show all values[+]
optional, jsonarray List of item price ids for which this coupon is applicable. optional, list of item_constraint_criteria
The list of item constraint criteria.
ItemConstraintCriteria attributes
enumerated string Item type for which this criteria is applicable for. Possible values are
PLANPlan is a type of itemADDONAddon is a type of itemCHARGECharge is a type of item
PLANPlan is a type of itemADDONAddon is a type of itemCHARGECharge is a type of item
Show all values[+]
optional, jsonarray List of currencies (ISO 4217 format) for which this coupon is applicable.
optional, jsonarray List of families for which this coupon is applicable.
optional, jsonarray List of frequencies for which this coupon is applicable. Allowed frequencies are [day, week, month, year]. optional, list of coupon_constraint
List of constraints applicable on the redemption of this coupon.
CouponConstraint attributes
enumerated string The resource type for the constraint. This, along with type and value, helps define the specific rule applied. Possible values are
CUSTOMERThe constraint is based on customer records.
enumerated string Type of coupon constraints Possible values are
MAX_REDEMPTIONSThe coupon can be redeemed up to a set number of times for a specific resource type. The maximum redemptions are specified using value, and the resource type is specified using entity_type. For example, if entity_type is customer and value is 10 then the coupon can only be redeemed up to 10 times for any particular customer record.UNIQUE_BYIndicates-when entity_type is customer-that the coupon can be redeemed only once for every unique value of a specified customer attribute. The customer attribute is specified using value. For example, if value is email, then the coupon can be redeemed only once for every unique value of customer.email. In other words, when there are multiple customer records with the same value for email, once the coupon has been redeemed for one of those customer records, no further redemptions of the coupon are allowed for any of those customer records.EXISTING_CUSTOMERThe coupon is applicable only for existing customer(s). A customer will be considered as existing_customer when they have at least one non-void, non-zero-dollar invoice.NEW_CUSTOMERThe coupon is applicable only for new customer(s). A customer will be considered as new_customer when they do not have any prior non-void, non-zero-dollar invoices.
MAX_REDEMPTIONSThe coupon can be redeemed up to a set number of times for a specific resource type. The maximum redemptions are specified using value, and the resource type is specified using entity_type. For example, if entity_type is customer and value is 10 then the coupon can only be redeemed up to 10 times for any particular customer record.UNIQUE_BYIndicates-when entity_type is customer-that the coupon can be redeemed only once for every unique value of a specified customer attribute. The customer attribute is specified using value. For example, if value is email, then the coupon can be redeemed only once for every unique value of customer.email. In other words, when there are multiple customer records with the same value for email, once the coupon has been redeemed for one of those customer records, no further redemptions of the coupon are allowed for any of those customer records.EXISTING_CUSTOMERThe coupon is applicable only for existing customer(s). A customer will be considered as existing_customer when they have at least one non-void, non-zero-dollar invoice.NEW_CUSTOMERThe coupon is applicable only for new customer(s). A customer will be considered as new_customer when they do not have any prior non-void, non-zero-dollar invoices.
Show all values[+]
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.
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.
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.
optional, string, max chars=100 Display name used in invoice. If it is not configured then name is used in invoice.
enumerated string, default=percentage Specifies the type of discount to be applied. Possible values are
FIXED_AMOUNTA fixed amount is deducted as a discount. The discount amount is specified in discount_amount. PERCENTAGEA percentage of the original price is deducted as a discount. The discount percentage is specified in discount_percentage. OFFER_QUANTITYA specified number of units of the item price are offered for free. The number of free units is specified in discount_quantity. The offer_quantity option is valid only when apply_on is set to each_specified_item and the pricing_model of the item price is per_unit. FIXED_AMOUNTA fixed amount is deducted as a discount. The discount amount is specified in discount_amount. PERCENTAGEA percentage of the original price is deducted as a discount. The discount percentage is specified in discount_percentage. OFFER_QUANTITYA specified number of units of the item price are offered for free. The number of free units is specified in discount_quantity. The offer_quantity option is valid only when apply_on is set to each_specified_item and the pricing_model of the item price is per_unit. Show all values[+]
optional, double, min=0.01, max=100.0 The percentage of the original amount that should be deducted from it.
optional, in cents, min=0 The value of the deduction. The format of this value depends on the kind of currency.
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.
optional, string, max chars=3 The currency code (ISO 4217 format) of the coupon. Applicable for fixed_amount coupons alone.
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.
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.
Show all values[+]
optional, timestamp(UTC) in seconds The date from which the coupon can be applied to subscriptions.
optional, timestamp(UTC) in seconds Date upto which the coupon can be applied to new subscriptions.
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.
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.DELETEDIndicates the coupon has been deleted.FUTUREThe 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. 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.DELETEDIndicates the coupon has been deleted. FUTUREThe 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.
Show all values[+]
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 item price specified by item_price_id.
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 item price specified by item_price_id.
Show all values[+]
timestamp(UTC) in seconds Timestamp indicating when this coupon is created.
optional, timestamp(UTC) in seconds Timestamp indicating when this coupon was archived.
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.
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.
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.
optional, enumerated string The unit of time for period. Applicable only when duration_type is limited_period. Possible values are
DAYA period of 24 hours.WEEKA period of 7 days.MONTHA period of 1 calendar month.YEARA period of 1 calendar year.
DAYA period of 24 hours.WEEKA period of 7 days.MONTHA period of 1 calendar month.YEARA period of 1 calendar year.
Show all values[+]
optional, integer, min=0 The number of times this coupon has been redeemed.
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.
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.
boolean Indicates whether the coupon has been deleted or not.
optional, list of item_constraint The list of item constraints.
optional, list of item_constraint_criteria The list of item constraint criteria.
optional, list of coupon_constraint List of constraints applicable on the redemption of this coupon. This API creates a new coupon for a specific promotion or offers.
This API is not enabled for live sites by default. Please contact
support to get this enabled.
Sample Codes
import java.io.IOException;
import com.chargebee.*;
import com.chargebee.models.*;
import com.chargebee.models.enums.*;
public class Sample{
public static void main(String args[]) throws IOException{
Environment.configure("{site}","{site_api_key}");
Result result = Coupon.createForItems()
.id("summer_offer")
.name("Summer Offer")
.discountPercentage(10)
.discountType(DiscountType.PERCENTAGE)
.durationType(DurationType.FOREVER)
.applyOn(ApplyOn.EACH_SPECIFIED_ITEM)
.itemConstraintConstraint(0,Constraint.ALL)
.itemConstraintItemType(0,ItemType.PLAN)
.request();
Coupon coupon = result.coupon();
System.out.println(result);
}
}import java.io.IOException;
import com.chargebee.*;
import com.chargebee.models.*;
import com.chargebee.models.enums.*;
public class Sample{
public static void main(String args[]) throws IOException{
Environment.configure("{site}","{site_api_key}");
Result result = Coupon.createForItems()
.id("welcome_offer")
.name("Welcome Offer")
.discountPercentage(15)
.discountType(DiscountType.PERCENTAGE)
.durationType(DurationType.ONE_TIME)
.applyOn(ApplyOn.INVOICE_AMOUNT)
.couponConstraintEntityType(0,EntityType.CUSTOMER)
.couponConstraintType(0,Type.NEW_CUSTOMER)
.couponConstraintValue(0,"based_on_invoice")
.request();
Coupon coupon = result.coupon();
System.out.println(result);
}
}
copy full code
Click to Copy
Environment.configure("{site}","{site_api_key}");
Result result = Coupon.createForItems()
.id("summer_offer")
.name("Summer Offer")
.discountPercentage(10)
.discountType(DiscountType.PERCENTAGE)
.durationType(DurationType.FOREVER)
.applyOn(ApplyOn.EACH_SPECIFIED_ITEM)
.itemConstraintConstraint(0,Constraint.ALL)
.itemConstraintItemType(0,ItemType.PLAN)
.request();
Coupon coupon = result.coupon();
Environment.configure("{site}","{site_api_key}");
Result result = Coupon.createForItems()
.id("welcome_offer")
.name("Welcome Offer")
.discountPercentage(15)
.discountType(DiscountType.PERCENTAGE)
.durationType(DurationType.ONE_TIME)
.applyOn(ApplyOn.INVOICE_AMOUNT)
.couponConstraintEntityType(0,EntityType.CUSTOMER)
.couponConstraintType(0,Type.NEW_CUSTOMER)
.couponConstraintValue(0,"based_on_invoice")
.request();
Coupon coupon = result.coupon();
copy snippet
Click to Copy
Environment.configure("{site}","{site_api_key}");
Result result = Coupon.createForItems()
.id("summer_offer")
.name("Summer Offer")
.discountPercentage(10)
.discountType(DiscountType.PERCENTAGE)
.durationType(DurationType.FOREVER)
.applyOn(ApplyOn.EACH_SPECIFIED_ITEM)
.itemConstraintConstraint(0,Constraint.ALL)
.itemConstraintItemType(0,ItemType.PLAN)
.request();
Coupon coupon = result.coupon();
Environment.configure("{site}","{site_api_key}");
Result result = Coupon.createForItems()
.id("summer_offer")
.name("Summer Offer")
.discountPercentage(10)
.discountType(DiscountType.PERCENTAGE)
.durationType(DurationType.FOREVER)
.applyOn(ApplyOn.EACH_SPECIFIED_ITEM)
.itemConstraintConstraint(0,Constraint.ALL)
.itemConstraintItemType(0,ItemType.PLAN)
.request();
Coupon coupon = result.coupon();
Create a coupon for items with constraints
Environment.configure("{site}","{site_api_key}");
Result result = Coupon.createForItems()
.id("welcome_offer")
.name("Welcome Offer")
.discountPercentage(15)
.discountType(DiscountType.PERCENTAGE)
.durationType(DurationType.ONE_TIME)
.applyOn(ApplyOn.INVOICE_AMOUNT)
.couponConstraintEntityType(0,EntityType.CUSTOMER)
.couponConstraintType(0,Type.NEW_CUSTOMER)
.couponConstraintValue(0,"based_on_invoice")
.request();
Coupon coupon = result.coupon();
Sample Result [ JSON ]
Show more...
{
"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
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.
.
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.
.
optional, string, max chars=100 Display name used in invoice. If it is not configured then name is used in invoice.
optional, enumerated string, default=percentage Specifies the type of discount to be applied. Possible values are
FIXED_AMOUNTA fixed amount is deducted as a discount. The discount amount is specified in discount_amount. PERCENTAGEA percentage of the original price is deducted as a discount. The discount percentage is specified in discount_percentage. OFFER_QUANTITYA specified number of units of the item price are offered for free. The number of free units is specified in discount_quantity. The offer_quantity option is valid only when apply_on is set to each_specified_item and the pricing_model of the item price is per_unit. FIXED_AMOUNTA fixed amount is deducted as a discount. The discount amount is specified in discount_amount. PERCENTAGEA percentage of the original price is deducted as a discount. The discount percentage is specified in discount_percentage. OFFER_QUANTITYA specified number of units of the item price are offered for free. The number of free units is specified in discount_quantity. The offer_quantity option is valid only when apply_on is set to each_specified_item and the pricing_model of the item price is per_unit. Show all values[+] discountAmount[(val)](val)
optional, in cents, min=0 The value of the deduction. The format of this value depends on the kind of currency.
required if Multicurrency is enabled, string, max chars=3 The currency code (ISO 4217 format) of the coupon. Applicable for fixed_amount coupons alone. discountPercentage[(val)](val)
optional, double, min=0.01, max=100.0 The percentage of the original amount that should be deducted from it. discountQuantity[(val)](val)
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.
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 item price specified by item_price_id.
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 item price specified by item_price_id.
Show all values[+]
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.
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.
Show all values[+] durationMonth[(val)](val)
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.
optional, timestamp(UTC) in seconds The date from which the coupon can be applied to subscriptions.
optional, timestamp(UTC) in seconds Date upto which the coupon can be applied to new subscriptions. maxRedemptions[(val)](val)
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.
.
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.
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. includedInMrr[(val)](val)
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.
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.
optional, enumerated string The unit of time for period. Applicable only when duration_type is limited_period. Possible values are
DAYA period of 24 hours.WEEKA period of 7 days.MONTHA period of 1 calendar month.YEARA period of 1 calendar year.
DAYA period of 24 hours.WEEKA period of 7 days.MONTHA period of 1 calendar month.YEARA period of 1 calendar year.
Show all values[+]
optional, enumerated string, default=active Status of the coupon. Possible values are
ACTIVECan be applied to a subscription.ARCHIVEDCannot be applied to a subscription. Existing associations remain unaffected.
ACTIVECan be applied to a subscription.ARCHIVEDCannot be applied to a subscription. Existing associations remain unaffected.
Show all values[+]
optional, array Parameters for itemConstraints. Multiple itemConstraints can be passed by specifying unique indices.
optional, array Parameters for itemConstraintCriteria. Multiple itemConstraintCriteria can be passed by specifying unique indices.
optional, array Parameters for couponConstraints. Multiple couponConstraints can be passed by specifying unique indices.
Parameters for itemConstraints. Multiple itemConstraints can be passed by specifying unique indices.
methods are prefixed like itemConstraints<param name>(idx,val)
itemConstraintConstraint(idx,val) required, enumerated string Constraint applicable for the item Possible values are
NONECoupon not applicable to any items.ALLCoupon applicable to all items.SPECIFICCoupon applicable to specific items.CRITERIACoupon applicable based on criteria.
NONECoupon not applicable to any items.ALLCoupon applicable to all items.SPECIFICCoupon applicable to specific items.CRITERIACoupon applicable based on criteria.
Show all values[+] itemConstraintItemType(idx,val) required, enumerated string Item type for which this criteria is applicable for. Possible values are
PLANPlanADDONAddonCHARGECharge
itemConstraintItemPriceIds(idx,val) optional, jsonarray List of item price ids for which this coupon is applicable.
Note:
When specifying a value for item_price_ids, make sure that the value is wrapped in square brackets ([]), for example:
[cbdemo_advanced-USD-Daily] instead of cbdemo_advanced-USD-Daily; otherwise, a param_wrong_value error returns.
For information about item_price_ids, refer to Defining Price Points in Plans, Addons,
and Charges.
Parameters for itemConstraintCriteria. Multiple itemConstraintCriteria can be passed by specifying unique indices.
methods are prefixed like itemConstraintCriteria<param name>(idx,val)
itemConstraintCriteriaItemType(idx,val) optional, enumerated string Item type for which this criteria is applicable for. Possible values are
PLANPlan is a type of itemADDONAddon is a type of itemCHARGECharge is a type of item
PLANPlan is a type of itemADDONAddon is a type of itemCHARGECharge is a type of item
Show all values[+] itemConstraintCriteriaItemFamilyIds(idx,val) optional, jsonarray List of families for which this coupon is applicable. itemConstraintCriteriaCurrencies(idx,val) optional, jsonarray List of currencies (ISO 4217 format) for which this coupon is applicable. itemConstraintCriteriaItemPricePeriods(idx,val) optional, jsonarray Pass the item price period units for this criterion. period followed by period_units. Such as [1 day,1 week,3 month,6 month]
Parameters for couponConstraints. Multiple couponConstraints can be passed by specifying unique indices.
methods are prefixed like couponConstraints<param name>(idx,val)
couponConstraintEntityType(idx,val) required, enumerated string The resource type for the constraint. This, along with type and value, helps define the specific rule applied. Possible values are
CUSTOMERThe constraint is based on customer records.
couponConstraintType(idx,val) required, enumerated string The type of coupon constraint. Possible values are
MAX_REDEMPTIONSThe coupon can be redeemed up to a set number of times for a specific resource type. The maximum redemptions are specified using value, and the resource type is specified using entity_type. For example, if entity_type is customer and value is 10 then the coupon can only be redeemed up to 10 times for any particular customer record.UNIQUE_BYIndicates-when entity_type is customer-that the coupon can be redeemed only once for every unique value of a specified customer attribute. The customer attribute is specified using value. For example, if value is email, then the coupon can be redeemed only once for every unique value of customer.email. In other words, when there are multiple customer records with the same value for email, once the coupon has been redeemed for one of those customer records, no further redemptions of the coupon are allowed for any of those customer records.EXISTING_CUSTOMERThe coupon is applicable only for existing customer(s). A customer will be considered as existing_customer when they have at least one non-void, non-zero-dollar invoice.NEW_CUSTOMERThe coupon is applicable only for new customer(s). A customer will be considered as new_customer when they do not have any prior non-void, non-zero-dollar invoices.
MAX_REDEMPTIONSThe coupon can be redeemed up to a set number of times for a specific resource type. The maximum redemptions are specified using value, and the resource type is specified using entity_type. For example, if entity_type is customer and value is 10 then the coupon can only be redeemed up to 10 times for any particular customer record.UNIQUE_BYIndicates-when entity_type is customer-that the coupon can be redeemed only once for every unique value of a specified customer attribute. The customer attribute is specified using value. For example, if value is email, then the coupon can be redeemed only once for every unique value of customer.email. In other words, when there are multiple customer records with the same value for email, once the coupon has been redeemed for one of those customer records, no further redemptions of the coupon are allowed for any of those customer records.EXISTING_CUSTOMERThe coupon is applicable only for existing customer(s). A customer will be considered as existing_customer when they have at least one non-void, non-zero-dollar invoice.NEW_CUSTOMERThe coupon is applicable only for new customer(s). A customer will be considered as new_customer when they do not have any prior non-void, non-zero-dollar invoices.
Show all values[+] couponConstraintValue(idx,val) 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.
always returned required
Resource object representing coupon
Sample admin console URL
https://{site}.chargebee.com/admin-console/coupons/123x
This API updates a coupon that is created for a specific promotion or offers.
This API is not enabled for live sites by default. Please contact
support to get this enabled.
Sample Codes
import java.io.IOException;
import com.chargebee.*;
import com.chargebee.models.*;
import com.chargebee.models.enums.*;
public class Sample{
public static void main(String args[]) throws IOException{
Environment.configure("{site}","{site_api_key}");
Result result = Coupon.updateForItems("sample_coupon")
.discountPercentage(20)
.itemConstraintConstraint(0,Constraint.ALL)
.itemConstraintItemType(0,ItemType.PLAN)
.itemConstraintConstraint(1,Constraint.ALL)
.itemConstraintItemType(1,ItemType.ADDON)
.request();
Coupon coupon = result.coupon();
System.out.println(result);
}
}import java.io.IOException;
import com.chargebee.*;
import com.chargebee.models.*;
import com.chargebee.models.enums.*;
public class Sample{
public static void main(String args[]) throws IOException{
Environment.configure("{site}","{site_api_key}");
Result result = Coupon.updateForItems("welcome_offer")
.name("return_offer")
.discountPercentage(25)
.couponConstraintEntityType(0,EntityType.CUSTOMER)
.couponConstraintType(0,Type.EXISTING_CUSTOMER)
.couponConstraintValue(0,"based_on_invoice")
.request();
Coupon coupon = result.coupon();
System.out.println(result);
}
}
copy full code
Click to Copy
Environment.configure("{site}","{site_api_key}");
Result result = Coupon.updateForItems("sample_coupon")
.discountPercentage(20)
.itemConstraintConstraint(0,Constraint.ALL)
.itemConstraintItemType(0,ItemType.PLAN)
.itemConstraintConstraint(1,Constraint.ALL)
.itemConstraintItemType(1,ItemType.ADDON)
.request();
Coupon coupon = result.coupon();
Environment.configure("{site}","{site_api_key}");
Result result = Coupon.updateForItems("welcome_offer")
.name("return_offer")
.discountPercentage(25)
.couponConstraintEntityType(0,EntityType.CUSTOMER)
.couponConstraintType(0,Type.EXISTING_CUSTOMER)
.couponConstraintValue(0,"based_on_invoice")
.request();
Coupon coupon = result.coupon();
copy snippet
Click to Copy
Environment.configure("{site}","{site_api_key}");
Result result = Coupon.updateForItems("sample_coupon")
.discountPercentage(20)
.itemConstraintConstraint(0,Constraint.ALL)
.itemConstraintItemType(0,ItemType.PLAN)
.itemConstraintConstraint(1,Constraint.ALL)
.itemConstraintItemType(1,ItemType.ADDON)
.request();
Coupon coupon = result.coupon();
Environment.configure("{site}","{site_api_key}");
Result result = Coupon.updateForItems("sample_coupon")
.discountPercentage(20)
.itemConstraintConstraint(0,Constraint.ALL)
.itemConstraintItemType(0,ItemType.PLAN)
.itemConstraintConstraint(1,Constraint.ALL)
.itemConstraintItemType(1,ItemType.ADDON)
.request();
Coupon coupon = result.coupon();
Update a coupon for items with constraints
Environment.configure("{site}","{site_api_key}");
Result result = Coupon.updateForItems("welcome_offer")
.name("return_offer")
.discountPercentage(25)
.couponConstraintEntityType(0,EntityType.CUSTOMER)
.couponConstraintType(0,Type.EXISTING_CUSTOMER)
.couponConstraintValue(0,"based_on_invoice")
.request();
Coupon coupon = result.coupon();
Sample Result [ JSON ]
Show more...
{
"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
Method
Coupon.updateForItems(<coupon_id>)
optional, 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.
.
optional, string, max chars=100 Display name used in invoice. If it is not configured then name is used in invoice.
optional, enumerated string, default=percentage Specifies the type of discount to be applied. Possible values are
FIXED_AMOUNTA fixed amount is deducted as a discount. The discount amount is specified in discount_amount. PERCENTAGEA percentage of the original price is deducted as a discount. The discount percentage is specified in discount_percentage. OFFER_QUANTITYA specified number of units of the item price are offered for free. The number of free units is specified in discount_quantity. The offer_quantity option is valid only when apply_on is set to each_specified_item and the pricing_model of the item price is per_unit. FIXED_AMOUNTA fixed amount is deducted as a discount. The discount amount is specified in discount_amount. PERCENTAGEA percentage of the original price is deducted as a discount. The discount percentage is specified in discount_percentage. OFFER_QUANTITYA specified number of units of the item price are offered for free. The number of free units is specified in discount_quantity. The offer_quantity option is valid only when apply_on is set to each_specified_item and the pricing_model of the item price is per_unit. Show all values[+] discountAmount[(val)](val)
optional, in cents, min=0 The value of the deduction. The format of this value depends on the kind of currency.
required if Multicurrency is enabled, string, max chars=3 The currency code (ISO 4217 format) of the coupon. Applicable for fixed_amount coupons alone. discountPercentage[(val)](val)
optional, double, min=0.01, max=100.0 The percentage of the original amount that should be deducted from it. discountQuantity[(val)](val)
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.
optional, 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 item price specified by item_price_id.
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 item price specified by item_price_id.
Show all values[+]
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.
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.
Show all values[+] durationMonth[(val)](val)
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.
optional, timestamp(UTC) in seconds The date from which the coupon can be applied to subscriptions.
optional, timestamp(UTC) in seconds Date upto which the coupon can be applied to new subscriptions. maxRedemptions[(val)](val)
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.
.
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.
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. includedInMrr[(val)](val)
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.
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.
optional, enumerated string The unit of time for period. Applicable only when duration_type is limited_period. Possible values are
DAYA period of 24 hours.WEEKA period of 7 days.MONTHA period of 1 calendar month.YEARA period of 1 calendar year.
DAYA period of 24 hours.WEEKA period of 7 days.MONTHA period of 1 calendar month.YEARA period of 1 calendar year.
Show all values[+]
optional, array Parameters for itemConstraints. Multiple itemConstraints can be passed by specifying unique indices.
optional, array Parameters for itemConstraintCriteria. Multiple itemConstraintCriteria can be passed by specifying unique indices.
optional, array Parameters for couponConstraints. Multiple couponConstraints can be passed by specifying unique indices.
Parameters for itemConstraints. Multiple itemConstraints can be passed by specifying unique indices.
methods are prefixed like itemConstraints<param name>(idx,val)
itemConstraintConstraint(idx,val) required, enumerated string Constraint applicable for the item Possible values are
NONECoupon not applicable to any items.ALLCoupon applicable to all items.SPECIFICCoupon applicable to specific items.CRITERIACoupon applicable based on criteria.
NONECoupon not applicable to any items.ALLCoupon applicable to all items.SPECIFICCoupon applicable to specific items.CRITERIACoupon applicable based on criteria.
Show all values[+] itemConstraintItemType(idx,val) required, enumerated string Item type for which this criteria is applicable for. Possible values are
PLANPlanADDONAddonCHARGECharge
itemConstraintItemPriceIds(idx,val) optional, jsonarray List of item price ids for which this coupon is applicable.
Note:
When specifying a value for item_price_ids, make sure that the value is wrapped in square brackets ([]), for example:
[cbdemo_advanced-USD-Daily] instead of cbdemo_advanced-USD-Daily; otherwise, a param_wrong_value error returns.
For information about item_price_ids, refer to Defining Price Points in Plans, Addons,
and Charges.
Parameters for itemConstraintCriteria. Multiple itemConstraintCriteria can be passed by specifying unique indices.
methods are prefixed like itemConstraintCriteria<param name>(idx,val)
itemConstraintCriteriaItemType(idx,val) optional, enumerated string Item type for which this criteria is applicable for. Possible values are
PLANPlan is a type of itemADDONAddon is a type of itemCHARGECharge is a type of item
PLANPlan is a type of itemADDONAddon is a type of itemCHARGECharge is a type of item
Show all values[+] itemConstraintCriteriaItemFamilyIds(idx,val) optional, jsonarray List of families for which this coupon is applicable. itemConstraintCriteriaCurrencies(idx,val) optional, jsonarray List of currencies (ISO 4217 format) for which this coupon is applicable. itemConstraintCriteriaItemPricePeriods(idx,val) optional, jsonarray Pass the item price period units for this criterion. period followed by period_units. Such as [1 day,1 week,3 month,6 month]
Parameters for couponConstraints. Multiple couponConstraints can be passed by specifying unique indices.
methods are prefixed like couponConstraints<param name>(idx,val)
couponConstraintEntityType(idx,val) required, enumerated string The resource type for the constraint. This, along with type and value, helps define the specific rule applied. Possible values are
CUSTOMERThe constraint is based on customer records.
couponConstraintType(idx,val) required, enumerated string The type of coupon constraint. Possible values are
MAX_REDEMPTIONSThe coupon can be redeemed up to a set number of times for a specific resource type. The maximum redemptions are specified using value, and the resource type is specified using entity_type. For example, if entity_type is customer and value is 10 then the coupon can only be redeemed up to 10 times for any particular customer record.UNIQUE_BYIndicates-when entity_type is customer-that the coupon can be redeemed only once for every unique value of a specified customer attribute. The customer attribute is specified using value. For example, if value is email, then the coupon can be redeemed only once for every unique value of customer.email. In other words, when there are multiple customer records with the same value for email, once the coupon has been redeemed for one of those customer records, no further redemptions of the coupon are allowed for any of those customer records.EXISTING_CUSTOMERThe coupon is applicable only for existing customer(s). A customer will be considered as existing_customer when they have at least one non-void, non-zero-dollar invoice.NEW_CUSTOMERThe coupon is applicable only for new customer(s). A customer will be considered as new_customer when they do not have any prior non-void, non-zero-dollar invoices.
MAX_REDEMPTIONSThe coupon can be redeemed up to a set number of times for a specific resource type. The maximum redemptions are specified using value, and the resource type is specified using entity_type. For example, if entity_type is customer and value is 10 then the coupon can only be redeemed up to 10 times for any particular customer record.UNIQUE_BYIndicates-when entity_type is customer-that the coupon can be redeemed only once for every unique value of a specified customer attribute. The customer attribute is specified using value. For example, if value is email, then the coupon can be redeemed only once for every unique value of customer.email. In other words, when there are multiple customer records with the same value for email, once the coupon has been redeemed for one of those customer records, no further redemptions of the coupon are allowed for any of those customer records.EXISTING_CUSTOMERThe coupon is applicable only for existing customer(s). A customer will be considered as existing_customer when they have at least one non-void, non-zero-dollar invoice.NEW_CUSTOMERThe coupon is applicable only for new customer(s). A customer will be considered as new_customer when they do not have any prior non-void, non-zero-dollar invoices.
Show all values[+] couponConstraintValue(idx,val) 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.
always returned required
Resource object representing coupon
Sample admin console URL
https://{site}.chargebee.com/admin-console/coupons/123x
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.
This API is not enabled for live sites by default. Please contact
support to get this enabled.
Sample Codes
import java.io.IOException;
import com.chargebee.*;
import com.chargebee.models.*;
import com.chargebee.models.enums.*;
public class Sample{
public static void main(String args[]) throws IOException{
Environment.configure("{site}","{site_api_key}");
ListResult result = Coupon.list()
.limit(5)
.durationType().is("forever")
.status().is("active")
.sortByCreatedAt(SortOrder.ASC)
.request();
for(ListResult.Entry entry:result) {
Coupon coupon = entry.coupon();
}
System.out.println(result);
}
}
copy full code
Click to Copy
Environment.configure("{site}","{site_api_key}");
ListResult result = Coupon.list()
.limit(5)
.durationType().is("forever")
.status().is("active")
.sortByCreatedAt(SortOrder.ASC)
.request();
for(ListResult.Entry entry:result) {
Coupon coupon = entry.coupon();
}
copy snippet
Click to Copy
Environment.configure("{site}","{site_api_key}");
ListResult result = Coupon.list()
.limit(5)
.durationType().is("forever")
.status().is("active")
.sortByCreatedAt(SortOrder.ASC)
.request();
for(ListResult.Entry entry:result) {
Coupon coupon = entry.coupon();
}
Environment.configure("{site}","{site_api_key}");
ListResult result = Coupon.list()
.limit(5)
.durationType().is("forever")
.status().is("active")
.sortByCreatedAt(SortOrder.ASC)
.request();
for(ListResult.Entry entry:result) {
Coupon coupon = entry.coupon();
}
Sample Result [ JSON ]
Show more...
{
"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
optional, integer, default=10, min=1, max=100 The number of resources to be returned.
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.
sortBy<Attribute>(<sort-order>) optional, string filter
Sorts based on the specified attribute.
Supported attributes : createdAt
Supported sort-orders : SortOrder.ASC, SortOrder.DESC
Example → sortByCreatedAt(SortOrder.asc)
This will sort the result based on the 'createdAt'
attribute in ascending(earliest first) order.
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.
. Possible values are : Supported operators : is, isNot, startsWith, in, notIn
Example → id().is(OFF2008) 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.
. methods are prefixed like id<param name>().<operator>(val) optional, string, min chars=1 filter
Possible values are :
Supported operators :
Example →
optional, string, min chars=1 filter
Possible values are :
Supported operators :
Example →
starts_with().<operator>(val) starts_with().<operator>(val) optional, string, min chars=1 filter
Possible values are :
Supported operators :
Example →
optional, string filter
Possible values are :
Supported operators :
Example →
optional, string filter
Possible values are :
Supported operators :
Example →
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.
. Possible values are : Supported operators : is, isNot, startsWith, in, notIn
Example → name().is(Offer 10) 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.
. methods are prefixed like name<param name>().<operator>(val) optional, string, min chars=1 filter
Possible values are :
Supported operators :
Example →
optional, string, min chars=1 filter
Possible values are :
Supported operators :
Example →
starts_with().<operator>(val) starts_with().<operator>(val) optional, string, min chars=1 filter
Possible values are :
Supported operators :
Example →
optional, string filter
Possible values are :
Supported operators :
Example →
optional, string filter
Possible values are :
Supported operators :
Example →
discountType().<operator>(val) discountType().<operator>(val) optional, enumerated string filter
The type of deduction. Possible values are : FIXED_AMOUNT, PERCENTAGE, OFFER_QUANTITY
Supported operators : is, isNot, in, notIn
Example → discountType().is(fixed_amount)
The type of deduction.
methods are prefixed like discountType<param name>().<operator>(val)
optional, enumerated string filter
Possible values are : FIXED_AMOUNT, PERCENTAGE, OFFER_QUANTITY
Supported operators :
Example →
optional, enumerated string filter
Possible values are : fixed_amount, percentage, offer_quantity
Supported operators :
Example →
optional, string filter
Possible values are :
Supported operators :
Example →
optional, string filter
Possible values are :
Supported operators :
Example →
durationType().<operator>(val) durationType().<operator>(val) 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, isNot, in, notIn
Example → durationType().is(forever)
Specifies the time duration for which this coupon is attached to the subscription.
methods are prefixed like durationType<param name>().<operator>(val)
optional, enumerated string filter
Possible values are : ONE_TIME, FOREVER, LIMITED_PERIOD
Supported operators :
Example →
optional, enumerated string filter
Possible values are : one_time, forever, limited_period
Supported operators :
Example →
optional, string filter
Possible values are :
Supported operators :
Example →
optional, string filter
Possible values are :
Supported operators :
Example →
optional, enumerated string filter
Status of the coupon. Possible values are : ACTIVE, EXPIRED, ARCHIVED, DELETED, FUTURE
Supported operators : is, isNot, in, notIn
Example → status().is(active)
Status of the coupon.
methods are prefixed like status<param name>().<operator>(val)
optional, enumerated string filter
Possible values are : ACTIVE, EXPIRED, ARCHIVED, DELETED, FUTURE
Supported operators :
Example →
optional, enumerated string filter
Possible values are : active, expired, archived, deleted, future
Supported operators :
Example →
optional, string filter
Possible values are :
Supported operators :
Example →
optional, string filter
Possible values are :
Supported operators :
Example →
applyOn().<operator>(val) applyOn().<operator>(val) 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, isNot, in, notIn
Example → applyOn().is(invoice_amount)
The amount on the invoice to which the coupon is applied.
methods are prefixed like applyOn<param name>().<operator>(val)
optional, enumerated string filter
Possible values are : INVOICE_AMOUNT, EACH_SPECIFIED_ITEM
Supported operators :
Example →
optional, enumerated string filter
Possible values are : invoice_amount, each_specified_item
Supported operators :
Example →
optional, string filter
Possible values are :
Supported operators :
Example →
optional, string filter
Possible values are :
Supported operators :
Example →
createdAt().<operator>(val) createdAt().<operator>(val) optional, timestamp(UTC) in seconds filter
Timestamp indicating when this coupon is created. Possible values are :
Supported operators : after, before, on, between
Example → createdAt().after(145222875)
Timestamp indicating when this coupon is created.
methods are prefixed like createdAt<param name>().<operator>(val)
optional, timestamp(UTC) in seconds filter
Possible values are :
Supported operators :
Example →
optional, timestamp(UTC) in seconds filter
Possible values are :
Supported operators :
Example →
optional, timestamp(UTC) in seconds filter
Possible values are :
Supported operators :
Example →
between().<operator>(val) between().<operator>(val) optional, string filter
Possible values are :
Supported operators :
Example →
updatedAt().<operator>(val) updatedAt().<operator>(val) 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. Possible values are :
Supported operators : after, before, on, between
Example → updatedAt().after(1243545465)
To filter based on updated at. This attribute will be present only if the resource has been updated after 2016-11-09.
methods are prefixed like updatedAt<param name>().<operator>(val)
optional, timestamp(UTC) in seconds filter
Possible values are :
Supported operators :
Example →
optional, timestamp(UTC) in seconds filter
Possible values are :
Supported operators :
Example →
optional, timestamp(UTC) in seconds filter
Possible values are :
Supported operators :
Example →
between().<operator>(val) between().<operator>(val) optional, string filter
Possible values are :
Supported operators :
Example →
currencyCode().<operator>(val) currencyCode().<operator>(val) optional, string filter The currency code (ISO 4217 format) of the coupon. Applicable for fixed_amount coupons alone. Possible values are : Supported operators : is, isNot, startsWith, in, notIn
Example → currencyCode().is(USD) The currency code (ISO 4217 format) of the coupon. Applicable for fixed_amount coupons alone. methods are prefixed like currencyCode<param name>().<operator>(val) optional, string, min chars=1 filter
Possible values are :
Supported operators :
Example →
optional, string, min chars=1 filter
Possible values are :
Supported operators :
Example →
starts_with().<operator>(val) starts_with().<operator>(val) optional, string, min chars=1 filter
Possible values are :
Supported operators :
Example →
optional, string filter
Possible values are :
Supported operators :
Example →
optional, string filter
Possible values are :
Supported operators :
Example →
always returned required
Resource object representing coupon
always returned 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`.
Sample admin console URL
https://{site}.chargebee.com/admin-console/coupons/123x
This API retrieves a specific coupon using the coupon ID.
This API is not enabled for live sites by default. Please contact
support to get this enabled.
Sample Codes
import java.io.IOException;
import com.chargebee.*;
import com.chargebee.models.*;
import com.chargebee.models.enums.*;
public class Sample{
public static void main(String args[]) throws IOException{
Environment.configure("{site}","{site_api_key}");
Result result = Coupon.retrieve("demo_offer").request();
Coupon coupon = result.coupon();
System.out.println(result);
}
}
copy full code
Click to Copy
Environment.configure("{site}","{site_api_key}");
Result result = Coupon.retrieve("demo_offer").request();
Coupon coupon = result.coupon();
copy snippet
Click to Copy
Environment.configure("{site}","{site_api_key}");
Result result = Coupon.retrieve("demo_offer").request();
Coupon coupon = result.coupon();
Environment.configure("{site}","{site_api_key}");
Result result = Coupon.retrieve("demo_offer").request();
Coupon coupon = result.coupon();
Sample Result [ JSON ]
Show more...
{
"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}
Method
Coupon.retrieve(<coupon_id>)
always returned required
Resource object representing coupon
Sample admin console URL
https://{site}.chargebee.com/admin-console/coupons/123x
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.
This API is not enabled for live sites by default. Please contact
support to get this enabled.
Sample Codes
import java.io.IOException;
import com.chargebee.*;
import com.chargebee.models.*;
import com.chargebee.models.enums.*;
public class Sample{
public static void main(String args[]) throws IOException{
Environment.configure("{site}","{site_api_key}");
Result result = Coupon.delete("beta").request();
Coupon coupon = result.coupon();
System.out.println(result);
}
}
copy full code
Click to Copy
Environment.configure("{site}","{site_api_key}");
Result result = Coupon.delete("beta").request();
Coupon coupon = result.coupon();
copy snippet
Click to Copy
Environment.configure("{site}","{site_api_key}");
Result result = Coupon.delete("beta").request();
Coupon coupon = result.coupon();
Environment.configure("{site}","{site_api_key}");
Result result = Coupon.delete("beta").request();
Coupon coupon = result.coupon();
Sample Result [ JSON ]
Show more...
{
"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
Method
Coupon.delete(<coupon_id>)
always returned required
Resource object representing coupon
Sample admin console URL
https://{site}.chargebee.com/admin-console/coupons/123x
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 Codes
import java.io.IOException;
import com.chargebee.*;
import com.chargebee.models.*;
import com.chargebee.models.enums.*;
public class Sample{
public static void main(String args[]) throws IOException{
Environment.configure("{site}","{site_api_key}");
Result result = Coupon.copy()
.fromSite("merchant-test")
.idAtFromSite("copy_coupon")
.request();
Coupon coupon = result.coupon();
System.out.println(result);
}
}
copy full code
Click to Copy
Environment.configure("{site}","{site_api_key}");
Result result = Coupon.copy()
.fromSite("merchant-test")
.idAtFromSite("copy_coupon")
.request();
Coupon coupon = result.coupon();
copy snippet
Click to Copy
Environment.configure("{site}","{site_api_key}");
Result result = Coupon.copy()
.fromSite("merchant-test")
.idAtFromSite("copy_coupon")
.request();
Coupon coupon = result.coupon();
Environment.configure("{site}","{site_api_key}");
Result result = Coupon.copy()
.fromSite("merchant-test")
.idAtFromSite("copy_coupon")
.request();
Coupon coupon = result.coupon();
Sample Result [ JSON ]
Show more...
{
"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
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.
required, string, max chars=100 Id of the coupon to be copied. The new coupon created in this site will have the same Id.
optional, string, max chars=100 Id of copied coupon in this site. forSiteMerging[(val)](val)
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.
always returned required
Resource object representing coupon
Sample admin console URL
https://{site}.chargebee.com/admin-console/coupons/123x
This API unarchives a specific coupon using the coupon ID.
This API is not enabled for live sites by default. Please contact
support to get this enabled.
Sample Codes
import java.io.IOException;
import com.chargebee.*;
import com.chargebee.models.*;
import com.chargebee.models.enums.*;
public class Sample{
public static void main(String args[]) throws IOException{
Environment.configure("{site}","{site_api_key}");
Result result = Coupon.unarchive("winter_offer").request();
Coupon coupon = result.coupon();
System.out.println(result);
}
}
copy full code
Click to Copy
Environment.configure("{site}","{site_api_key}");
Result result = Coupon.unarchive("winter_offer").request();
Coupon coupon = result.coupon();
copy snippet
Click to Copy
Environment.configure("{site}","{site_api_key}");
Result result = Coupon.unarchive("winter_offer").request();
Coupon coupon = result.coupon();
Environment.configure("{site}","{site_api_key}");
Result result = Coupon.unarchive("winter_offer").request();
Coupon coupon = result.coupon();
Sample Result [ JSON ]
Show more...
{
"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
Method
Coupon.unarchive(<coupon_id>)
always returned required
Resource object representing coupon
Sample admin console URL
https://{site}.chargebee.com/admin-console/coupons/123x
Settings
Configure SDK
