Settings
API Version
Product Catalog
Library

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

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

Model Class

 

      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.offer_quantityApplies a discount based on the number of free units offered in a per unit plan subscription without reducing the total quantity sold.
 
 Show all values[+]
 
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
  
 
 
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.
 
 Show all values[+]
 
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.
 
 Show all values[+]
 
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.
 
 Show all values[+]
 
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.
 
 Show all values[+]
 
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.
 
 Show all values[+]
 
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. 
 
 
  
id 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 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 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 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.offer_quantityApplies a discount based on the number of free units offered in a per unit plan subscription without reducing the total quantity sold.
 
 Show all values[+]
discount_percentage discount_percentage
 

          optional, double, min=0.01, max=100.0
 The percentage of the original amount that should be deducted from it. 
 
discount_amount 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 discount_quantity
 

          optional, integer, min=1
  
 
duration_type 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.
 
 Show all values[+]
duration_month 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 valid_till
 

          optional, timestamp(UTC) in seconds
 Date upto which the coupon can be applied to new subscriptions. 
 
max_redemptions 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 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.
 
 Show all values[+]
apply_on 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.
 
 Show all values[+]
plan_constraint 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.
 
 Show all values[+]
addon_constraint 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.
 
 Show all values[+]
created_at created_at
 

          timestamp(UTC) in seconds
 Timestamp indicating when this coupon is created. 
 
archived_at archived_at
 

          optional, timestamp(UTC) in seconds
 Timestamp indicating when this coupon was archived. 
 
plan_ids plan_ids
 

          optional, list of string
 List of plan ids for which this coupon is applicable. 
 
addon_ids addon_ids
 

          optional, list of string
 List of addon ids for which this coupon is applicable. 
 
redemptions redemptions
 

          optional, integer, min=0
 The number of times this coupon has been redeemed. 
 
invoice_notes 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. 
 
 
 
Consent Fields for Coupon
 
 
Custom Fields for Coupon
 
 

      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
      
Click to Copy
 
 
200:
 
OK
 
STATUS
 

    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
    
 
Method
 
 
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.offer_quantityApplies a discount based on the number of free units offered in a per unit plan subscription without reducing the total quantity sold.
 
 Show all values[+]
 
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. 
 
discount_quantity[]
 

      optional, integer, min=1 
  
 
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.
 
 Show all values[+]
 
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.
 
 Show all values[+]
 
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).
 
 Show all values[+]
 
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).
 
 Show all values[+]
 
plan_ids[[0..n]][0..n]
 

      optional, list of string 
 Identifier of the plan. 
 
addon_ids[[0..n]][0..n]
 

      optional, list of string 
 Identifier of the addon. 
 
 
    
 
Returns
 
coupon  coupon
 

      always returned 
 Resource object representing coupon
 
Sample admin console URL
 

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

      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
      
Click to Copy
 
 
200:
 
OK
 
STATUS
 

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

      always returned 
 Resource object representing coupon
next_offset  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`.
 
Sample admin console URL
 

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

      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
      
Click to Copy
 
 
200:
 
OK
 
STATUS
 

    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}
    
 
Method
 
  
   
 
    
 
Returns
 
coupon  coupon
 

      always returned 
 Resource object representing coupon
 
Sample admin console URL
 

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