Product Catalog
    Library
You are viewing the documentation for Chargebee API V2. If you're using the older version (V1), click here.

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

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

Retrieve a coupon code

Retrieves a specific coupon code details.
Sample Request 
curl  https://{site}.chargebee.com/api/v2/coupon_codes/CBC978B \
     -u {site_api_key}:
copy
curl  https://{site}.chargebee.com/api/v2/coupon_codes/CBC978B \
     -u {site_api_key}:

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}

Returns

coupon_code
always returned
Resource object representing coupon_code

List coupon codes

List the available coupon codes.
Sample Request 
curl  https://{site}.chargebee.com/api/v2/coupon_codes \
     -G  \
     -u {site_api_key}:\
     --data-urlencode limit=2
copy
curl  https://{site}.chargebee.com/api/v2/coupon_codes \
     -G  \
     -u {site_api_key}:\
     --data-urlencode limit=2

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

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.
Supported operators : is, is_not, starts_with, in, not_in

Example → code[is] = "OFF2009"
coupon_id[<operator>]
optional, string filter
Id of the main coupon resource.
Supported operators : is, is_not, starts_with, in, not_in

Example → coupon_id[is] = "OFF20"
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.
Supported operators : is, is_not, starts_with

Example → coupon_set_name[is_not] = "OFF20"
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"

Returns

coupon_code
always returned
Resource object representing coupon_code
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”.

Archive a coupon code

Idempotency Supported
Archives a coupon code thereby making it inactive. The archived coupon code cannot be applied to any subscription.
Sample Request 
curl  https://{site}.chargebee.com/api/v2/coupon_codes/CBC978C/archive \
     -X POST  \
     -u {site_api_key}:
copy
curl  https://{site}.chargebee.com/api/v2/coupon_codes/CBC978C/archive \
     -X POST  \
     -u {site_api_key}:

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

Returns

coupon_code
always returned
Resource object representing coupon_code