Settings
API Version
Product Catalog
Library

Coupon codes

Coupon codes are used along with existing coupons in Chargebee. You can create a coupon set using a bunch of coupon codes and this coupon set will be associated with an existing coupon. A coupon code can only be applied to a single subscription and cannot be re-used.

Using coupon codes you can distribute several unique codes for a single main coupon, when you are running promotions.

Sample coupon code [ JSON ]

{ "code": "CBC978B", "coupon_id": "alpha", "coupon_set_id": "cs_3Rtysnm", "coupon_set_name": "Offer", "object": "coupon_code", "status": "not_redeemed" }

API Index URL

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

Model Class

 

      Coupon code attributes
      
 
code
 

      string, max chars=50
 Unique coupon code that can be redeemed only once. 
 
 
status
 

      enumerated string, default=not_redeemed
 Status of the coupon code. 
 
Possible values are
 
 
not_redeemedCan be applied to a subscription.redeemedCannot be applied to a subscription as the coupon code has been already used.archivedCannot be applied to a subscription as it has been made inactive.
 
 Show all values[+]
 
coupon_id
 

      string, max chars=100
 Id of the main coupon resource. 
 
 
coupon_set_id
 

      string, max chars=50
 Uniquely identifies a coupon_set 
 
 
coupon_set_name
 

      string, max chars=50
 Coupon set name to which this coupon code would be grouped under. If the coupon set with the passed name is not present, a new coupon set will be created. 
 
 
 
Event types
 

      This is a list of the event types we currently support. We will continue
      to add more events moving forward. All events follow a uniform pattern -
      <resource>_<event_name>. The resources that will be
      present in the event content are provided beneath each event type's
      description.
    
 
Note: If consolidated invoicing is enabled, the
      attributes invoice.subscription_id and
      credit_note.subscription_id should not be used
      (as it will not be present if the invoice / credit note has lines from
      multiple subscriptions). Instead to know the related subscriptions,
      their line_items' subscription_id attribute should be referred.
    
 
 
code code
 

          string, max chars=50
 Unique coupon code that can be redeemed only once. 
 
status status
 

          enumerated string, default=not_redeemed
 Status of the coupon code. 
 
Possible values are
 
 
not_redeemedCan be applied to a subscription.redeemedCannot be applied to a subscription as the coupon code has been already used.archivedCannot be applied to a subscription as it has been made inactive.
 
 Show all values[+]
coupon_id coupon_id
 

          string, max chars=100
 Id of the main coupon resource. 
 
coupon_set_id coupon_set_id
 

          string, max chars=50
 Uniquely identifies a coupon_set 
 
coupon_set_name coupon_set_name
 

          string, max chars=50
 Coupon set name to which this coupon code would be grouped under. If the coupon set with the passed name is not present, a new coupon set will be created. 
 
 
 
Consent Fields for Coupon code
 
 
Custom Fields for Coupon code
 
  

      Retrieve a coupon code
      
  
 
  Try in API Explorer
   
Retrieves a specific coupon code details.
  
Notes
 
 

        Sample Request
      
 

  Try in API Explorer

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

      copy
      
Click to Copy
 
 
200:
 
OK
 
STATUS
 

    Sample Response [ JSON ]
 
Show more...
 
{
    "coupon_code": {
        "code": "CBC978B",
        "coupon_id": "alpha",
        "coupon_set_id": "cs_3Rtysnm",
        "coupon_set_name": "Offer",
        "object": "coupon_code",
        "status": "not_redeemed"
    }
}
 

      URL Format
      GET
 

      https://{site}.chargebee.com/api/v2/coupon_codes/{coupon-code-code}
    
 
Method
 
  
   
 
    
 
Returns
 
coupon_code  coupon_code
 

      always returned 
 Resource object representing coupon_code
 
Sample admin console URL
 

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

      List coupon codes
      
  
 
  Try in API Explorer
   
List the available coupon codes.
  
Notes
 
 

        Sample Request
      
 

  Try in API Explorer

 
 
curl  https://{site}.chargebee.com/api/v2/coupon_codes \
     -G  \
     -u {site_api_key}:\
     --data-urlencode limit=2
 

      copy
      
Click to Copy
 
 
200:
 
OK
 
STATUS
 

    Sample Response [ JSON ]
 
Show more...
 
{
    "list": [
        {
            "coupon_code": {
                "code": "CBC090A",
                "coupon_id": "beta",
                "coupon_set_id": "cs_3RtyuMoOn",
                "coupon_set_name": "Launch Promotion",
                "object": "coupon_code",
                "status": "not_redeemed"
            }
        },
        {..}
    ],
    "next_offset": "[\"155000000004\"]"
}
 

      URL Format
      GET
 

      https://{site}.chargebee.com/api/v2/coupon_codes
    
 
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. 
   
 
   
Filter Params 
 

          For operator usages, see the
          Pagination and Filtering
          section.
        
 
code[<operator>]
  
 optional, string filter
 Unique coupon code that can be redeemed only once. Possible values are :  
Supported operators : is, is_not, starts_with, in, not_in
    

Example → code[is] = "OFF2009"
 
 
 
code[is][operator]
 
 optional, string, min chars=1 filter
  Possible values are :  
Supported operators : 
    

Example → 
 
code[is_not][operator]
 
 optional, string, min chars=1 filter
  Possible values are :  
Supported operators : 
    

Example → 
 
code[starts_with][operator]
 
 optional, string, min chars=1 filter
  Possible values are :  
Supported operators : 
    

Example → 
 
code[in][operator]
 
 optional, string filter
  Possible values are :  
Supported operators : 
    

Example → 
 
code[not_in][operator]
 
 optional, string filter
  Possible values are :  
Supported operators : 
    

Example → 
coupon_id[<operator>]
  
 optional, string filter
 Id of the main coupon resource. Possible values are :  
Supported operators : is, is_not, starts_with, in, not_in
    

Example → coupon_id[is] = "OFF20"
 
 
 
coupon_id[is][operator]
 
 optional, string, min chars=1 filter
  Possible values are :  
Supported operators : 
    

Example → 
 
coupon_id[is_not][operator]
 
 optional, string, min chars=1 filter
  Possible values are :  
Supported operators : 
    

Example → 
 
coupon_id[starts_with][operator]
 
 optional, string, min chars=1 filter
  Possible values are :  
Supported operators : 
    

Example → 
 
coupon_id[in][operator]
 
 optional, string filter
  Possible values are :  
Supported operators : 
    

Example → 
 
coupon_id[not_in][operator]
 
 optional, string filter
  Possible values are :  
Supported operators : 
    

Example → 
coupon_set_name[<operator>]
  
 optional, string filter
 Coupon set name to which this coupon code would be grouped under. If the coupon set with the passed name is not present, a new coupon set will be created. Possible values are :  
Supported operators : is, is_not, starts_with
    

Example → coupon_set_name[is] = "OFF20"
 
 
 
coupon_set_name[is][operator]
 
 optional, string, min chars=1 filter
  Possible values are :  
Supported operators : 
    

Example → 
 
coupon_set_name[is_not][operator]
 
 optional, string, min chars=1 filter
  Possible values are :  
Supported operators : 
    

Example → 
 
coupon_set_name[starts_with][operator]
 
 optional, string, min chars=1 filter
  Possible values are :  
Supported operators : 
    

Example → 
status[<operator>]
  
 optional, enumerated string filter
 Status of the coupon code.  Possible values are : not_redeemed, redeemed, archived 
Supported operators : is, is_not, in, not_in
    

Example → status[is] = "redeemed"
 
 
 
status[is][operator]
 
 optional, enumerated string filter
  Possible values are : not_redeemed, redeemed, archived 
Supported operators : 
    

Example → 
 
status[is_not][operator]
 
 optional, enumerated string filter
  Possible values are : not_redeemed, redeemed, archived 
Supported operators : 
    

Example → 
 
status[in][operator]
 
 optional, string filter
  Possible values are :  
Supported operators : 
    

Example → 
 
status[not_in][operator]
 
 optional, string filter
  Possible values are :  
Supported operators : 
    

Example → 
 
Returns
 
coupon_code  coupon_code
 

      always returned 
 Resource object representing coupon_code
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/coupon_codes/123x
    

      Archive a coupon code
      
 
Idempotency Supported
 
 
  Try in API Explorer
   
Archives a coupon code thereby making it inactive. The archived coupon code cannot be applied to any subscription.
  
Notes
 
 

        Sample Request
      
 

  Try in API Explorer

 
 
curl  https://{site}.chargebee.com/api/v2/coupon_codes/CBC978C/archive \
     -X POST  \
     -u {site_api_key}:
 

      copy
      
Click to Copy
 
 
200:
 
OK
 
STATUS
 

    Sample Response [ JSON ]
 
Show more...
 
{
    "coupon_code": {
        "code": "CBC978C",
        "coupon_id": "sample_coupon",
        "coupon_set_id": "cs_3RtyuMoOV",
        "coupon_set_name": "promotion offer",
        "object": "coupon_code",
        "status": "archived"
    }
}
 

      URL Format
      POST
 

      https://{site}.chargebee.com/api/v2/coupon_codes/{coupon-code-code}/archive
    
 
Method
 
  
   
 
    
 
Returns
 
coupon_code  coupon_code
 

      always returned 
 Resource object representing coupon_code
 
Sample admin console URL
 

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