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

A coupon set contains a bunch of coupon codes that can be redeemed by your customers when they are checking out. It belongs to an existing coupon and will usually be combined with other coupons that share similar promotion or discount offers. Using this resource, you can create, update, retrieve, delete coupon sets and add coupon codes to a coupon set.

Sample coupon set [ JSON ]

{ "archived_count": 0, "coupon_id": "beta", "id": "cs_3RtyuIHol", "name": "Launch Promotion", "object": "coupon_set", "redeemed_count": 0, "total_count": 0 }
id
string, max chars=50
Uniquely identifies a coupon_set.
coupon_id
string, max chars=100
Coupon id linked to coupon set.
name
string, max chars=50
Name of the coupon set.
total_count
optional, integer
No of coupon codes present in coupon set.
redeemed_count
optional, integer
No of redeemed codes.
archived_count
optional, integer
No of archived codes.
Create a coupon set with a coupon code compatible to your product offers and promotional discounts.
Sample Request
curl  https://{site}.chargebee.com/api/v2/coupon_sets \
     -u {site_api_key}:\
     -d coupon_id="beta" \
     -d name="Launch Promotion" \
     -d id="cs_3RtyuIHol"
copy
curl  https://{site}.chargebee.com/api/v2/coupon_sets \
     -u {site_api_key}:\
     -d coupon_id="beta" \
     -d name="Launch Promotion" \
     -d id="cs_3RtyuIHol"

Sample Response [ JSON ]

Show more...
{"coupon_set": { "archived_count": 0, "coupon_id": "beta", "id": "cs_3RtyuIHol", "name": "Launch Promotion", "object": "coupon_set", "redeemed_count": 0, "total_count": 0 }}

URL Format POST

https://{site}.chargebee.com/api/v2/coupon_sets
coupon_id
required, string, max chars=100
Coupon id linked to coupon set.
name
required, string, max chars=50
Name of the coupon set.
id
required, string, max chars=50
Uniquely identifies a coupon_set.
meta_data
optional, jsonobject
A set of key-value pairs stored as additional information for the subscription. Learn more.
always returned
Resource object representing coupon_set.

This API add coupon codes to an existing coupon set.

Sample Request
curl  https://{site}.chargebee.com/api/v2/coupon_sets/cs_3RtyuLol/add_coupon_codes \
     -u {site_api_key}:\
     -d code[0]="CBCC789"
copy
curl  https://{site}.chargebee.com/api/v2/coupon_sets/cs_3RtyuLol/add_coupon_codes \
     -u {site_api_key}:\
     -d code[0]="CBCC789"

Sample Response [ JSON ]

Show more...
{"coupon_set": { "archived_count": 0, "coupon_id": "sample_coupon", "id": "cs_3RtyuLol", "name": "Weekend Offer", "object": "coupon_set", "redeemed_count": 0, "total_count": 1 }}

URL Format POST

https://{site}.chargebee.com/api/v2/coupon_sets/{coupon_set_id}/add_coupon_codes
code[0..n]
optional, list of string
You can pass up to 100 values per API call. You can also use the Chargebee UI to pass up to 1000 codes per operation. There is no limit on the total number of coupon codes that can be included in a coupon set.
always returned
Resource object representing coupon_set.
Use this API to get the list of all the coupon sets.
Sample Request
curl  https://{site}.chargebee.com/api/v2/coupon_sets \
     -G  \
     -u {site_api_key}:\
     --data-urlencode limit=2
copy
curl  https://{site}.chargebee.com/api/v2/coupon_sets \
     -G  \
     -u {site_api_key}:\
     --data-urlencode limit=2

Sample Response [ JSON ]

Show more...
{ "list": [ {"coupon_set": { "archived_count": 0, "coupon_id": "sample_coupon", "id": "cs_3RtyuLol", "name": "Weekend Offer", "object": "coupon_set", "redeemed_count": 0, "total_count": 1 }}, {..} ], "next_offset": "[\"154000000001\",\"1517501418000\"]" }

URL Format GET

https://{site}.chargebee.com/api/v2/coupon_sets
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.
id[<operator>]
optional, string filter
Uniquely identifies a coupon_set.
Supported operators : is, is_not, starts_with, in, not_in

Example id[is] = "bulk-codes-1"
name[<operator>]
optional, string filter
Name of the coupon set.
Supported operators : is, is_not, starts_with, in, not_in

Example name[is] = "bulk-codes-1"
coupon_id[<operator>]
optional, string filter
Coupon id linked to coupon set.
Supported operators : is, is_not, starts_with, in, not_in

Example coupon_id[is] = "OFF2008"
total_count[<operator>]
optional, integer filter
No of coupon codes present in coupon set.
Supported operators : is, is_not, lt, lte, gt, gte, between

Example total_count[is] = "10"
redeemed_count[<operator>]
optional, integer filter
No of redeemed codes.
Supported operators : is, is_not, lt, lte, gt, gte, between

Example redeemed_count[gte] = "5"
archived_count[<operator>]
optional, integer filter
No of archived codes.
Supported operators : is, is_not, lt, lte, gt, gte, between

Example archived_count[is] = "2"
always returned
Resource object representing coupon_set.
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”.

Use this API to retrieve a specific coupon set.

Sample Request
curl  https://{site}.chargebee.com/api/v2/coupon_sets/cs_3RtyuLop \
     -u {site_api_key}:
copy
curl  https://{site}.chargebee.com/api/v2/coupon_sets/cs_3RtyuLop \
     -u {site_api_key}:

Sample Response [ JSON ]

Show more...
{"coupon_set": { "archived_count": 0, "coupon_id": "beta2", "id": "cs_3RtyuLop", "name": "Clearance Offer", "object": "coupon_set", "redeemed_count": 0, "total_count": 0 }}

URL Format GET

https://{site}.chargebee.com/api/v2/coupon_sets/{coupon_set_id}
always returned
Resource object representing coupon_set.

Use this API to update a specific coupon set by updating its name and the meta_data.

Sample Request
curl  https://{site}.chargebee.com/api/v2/coupon_sets/cs_3Rtyuqop/update \
     -X POST  \
     -u {site_api_key}:\
     -d name="Promotional Offer"
copy
curl  https://{site}.chargebee.com/api/v2/coupon_sets/cs_3Rtyuqop/update \
     -X POST  \
     -u {site_api_key}:\
     -d name="Promotional Offer"

Sample Response [ JSON ]

Show more...
{"coupon_set": { "archived_count": 0, "coupon_id": "beta3", "id": "cs_3Rtyuqop", "name": "Promotional Offer", "object": "coupon_set", "redeemed_count": 0, "total_count": 0 }}

URL Format POST

https://{site}.chargebee.com/api/v2/coupon_sets/{coupon_set_id}/update
name
optional, string, max chars=50
Name of the coupon set.
meta_data
optional, jsonobject
A set of key-value pairs stored as additional information for the subscription. Learn more.
always returned
Resource object representing coupon_set.
Use this endpoint to delete a specific coupon set.
Sample Request
curl  https://{site}.chargebee.com/api/v2/coupon_sets/cs_3Rtyupop/delete \
     -X POST  \
     -u {site_api_key}:
copy
curl  https://{site}.chargebee.com/api/v2/coupon_sets/cs_3Rtyupop/delete \
     -X POST  \
     -u {site_api_key}:

Sample Response [ JSON ]

Show more...
{"coupon_set": { "archived_count": 0, "coupon_id": "beta4", "id": "cs_3Rtyupop", "name": "Launch Offer", "object": "coupon_set", "redeemed_count": 0, "total_count": 0 }}

URL Format POST

https://{site}.chargebee.com/api/v2/coupon_sets/{coupon_set_id}/delete
always returned
Resource object representing coupon_set.

Use this API to delete all the unutilised coupon codes from a specific coupon set.

Sample Request
curl  https://{site}.chargebee.com/api/v2/coupon_sets/cs_3RtyuSuN/delete_unused_coupon_codes \
     -X POST  \
     -u {site_api_key}:
copy
curl  https://{site}.chargebee.com/api/v2/coupon_sets/cs_3RtyuSuN/delete_unused_coupon_codes \
     -X POST  \
     -u {site_api_key}:

Sample Response [ JSON ]

Show more...
{"coupon_set": { "archived_count": 0, "coupon_id": "beta5", "id": "cs_3RtyuSuN", "name": "Welcome Offer", "object": "coupon_set", "redeemed_count": 0, "total_count": 0 }}

URL Format POST

https://{site}.chargebee.com/api/v2/coupon_sets/{coupon_set_id}/delete_unused_coupon_codes
always returned
Resource object representing coupon_set.