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

Coupon sets

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 }

Coupon set attributes

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

Idempotency Supported
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

Input Parameters

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 coupon set. Learn more.

Returns

coupon_set
always returned
Resource object representing coupon_set

Add coupon codes to coupon set

Idempotency Supported

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

Input Parameters

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.

Returns

coupon_set
always returned
Resource object representing coupon_set

List coupon sets

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

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.
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_not] = "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_not] = "10"
redeemed_count[<operator>]
optional, integer filter
No of redeemed codes.
Supported operators : is, is_not, lt, lte, gt, gte, between

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

Example → archived_count[lt] = "2"

Returns

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

Retrieve a coupon set

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}

Returns

coupon_set
always returned
Resource object representing coupon_set

Update a coupon set

Idempotency Supported

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

Input Parameters

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 coupon set. Learn more.

Returns

coupon_set
always returned
Resource object representing coupon_set

Delete a coupon set

Idempotency Supported
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

Returns

coupon_set
always returned
Resource object representing coupon_set

Delete unused coupon codes

Idempotency Supported

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

Returns

coupon_set
always returned
Resource object representing coupon_set