Our documentation has moved!

You are currently viewing a legacy version of our help articles.
For the most up-to-date version, please use the new Chargify Help & Support Site.

Using the API to manage coupons

Developers can use the API to completely manage coupons, including the following actions:

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

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.

Was this article helpful?
2 out of 2 found this helpful
Have more questions? Submit a request


  • 0
    Test Test


  • 0
    Ken Granderson

    I am trying to integrate our Chargify product data into our database and need to be able to pull a read-only copy of the product data that shows on the Setup page so that I can store the various Chargify Ids in our database.

    I have tried, but I do not seem to be able to find an API that I can use to list all Coupons WITHOUT first knowing the Coupon Code or Id.

    Am I missing the API, or is there no such API for some reason that returns your current list of Coupon Codes / Ids without you already knowing them?

Please sign in to leave a comment.
Powered by Zendesk