Developers can use the API to completely manage coupons, including the following actions:
- Create new coupons
- Update exiting coupons
- Validate coupon codes
- Retrieve specific details about a coupon usage
- Create a new subscription using an existing coupon
- Add a coupon to an already existing subscription
- Remove a coupon from a subscription
- Archive existing coupons
This article will guide you thru all available actions. It assumes you have a chargify account with a valid product_family and a valid product. We’re going to use the command line tool CURL to execute calls to Chargify’s JSON API.
Creating a new coupon
Let’s start creating a new coupon. All you need to do is pass a valid coupon object to the
coupons endpoint, like this:
curl -i -H "Content-type: application/json" -X POST -T "coupon.json" "https://yoursite.chargify.com/coupons.json"
The contents of the coupon.json file is listed below. You can find more information about all available fields in the Coupon API section of the documentation website.
And here’s the expected response to this CURL call:
Updating an existing coupon
Ouch, we have wrongly set the end_date of this coupon to a specific date, but we don’t want it to expire. How should we proceed? The update coupon method is what we are looking for:
curl -i -H "Content-type: application/json" -X PUT -T "update.json" "https://yoursite.chargify.com/coupons/9.json"
The file update.json reads:
And the response should be:
Validating a Coupon code
Validate a coupon code using the API is really simple. Lets start trying out an invalid code:
curl -i -H "Accept: application/json" -H "Content-type: application/json" "https://yoursite.chargify.com/coupons/validate.json?coupon_code=INVALIDCODE"
The response should be:
If the coupon is valid but expired, the following response will be returned:
And if the coupon is archived, the returned response will be:
If the coupon is valid, blank page with ‘200 OK’ status will be returned.
Retrieving coupon usage
You can also retrieve usage details about your coupon. To do that, you should invoke the usage method:
curl -i -H "Accept: application/json" -H "Content-type: application/json" https://yoursite.chargify.com/coupons/9/usage.json
The response should be something like this:
Creating a new subscription using a coupon
You can easily create a subscription using a valid coupon. To do that, just post a valid JSON subscription and include a coupon code. For example:
Posting this to
https://yoursite.chargify.com/subscriptions.json will create a subscription discounted by the
Adding a coupon to an existing subscription
Sometimes you may want to add a coupon to an existing subscription. To do that, just use the
add_coupon endpoint in the subscription API. Here’s an example about how you can do that:
curl -i -H "Accept: application/json" -H "Content-type: application/json" "https://yoursite.chargify.com/ubscriptions/4/add_coupon.json?code=20OFF1" -d''
If the subscription already have a coupon attached to it, the following error will be returned with a 422 status:
Otherwise, the subscription is retuned with a 200 status.
Removing a coupon from an existing subscription
You can also remove a coupon from a discounted subscription using the API. To do that, follow this example:
curl -i -H "Accept: application/json" -H "Content-type: application/json" -X DELETE "https://yoursite.chargify.com/ubscriptions4/remove_coupon.json"
The following response will be retuned:
Archiving a coupon
We now want to archive the coupon we previously created. Here’s how you can do that:
`curl -i -H "Content-type: application/json" -X DELETE "https://yoursite.chargify.com/coupons/9.json"@
This call will mark the coupon as archived. An archived coupon cannot be used anymore. See the Validate coupon codes for more information about how check for archived coupons.