Chargify Documentation » API v1 Resources

API: Coupons

Coupons can be administered in the Admin Interface (see Coupons) or via the API. In addition to the normal CRUD actions on coupons, you can also create Subscriptions using a Coupon, add a Coupon to an existing Subscription, and validate a Coupon via the API.

URI/Method

Resource/URI	GET	POST	PUT	DELETE
Coupons `/coupons`	–	Create new coupon	–	–
Coupon `/coupon/<id>`	Retrieve coupon	–	Update coupon	Archive subscription
Coupon (by code) `/coupons/find`	Find by coupon code	–	–	–
Coupon Usage `/coupons/<id>/usage`	Retrieve Usage	–	–	–
Subscription `/subscriptions`	–	Create Subscription w/ Coupon	–	–
Subscription Coupon `/subscriptions/<id>/add_coupon`	–	Add Coupon to existing subscription	–	–
Subscription Coupon `/subscriptions/<id>/remove_coupon`	–	–	–	Remove Coupon from existing subscription

Coupon Input Attributes

When creating a coupon, you must specify a product family using the product_family_id. If no product_family_id is passed, the first product family available is used.

name The internal coupon name. This information is never displayed to customers.
code The coupon code. This is used by you or your customers to apply the coupon to a subscription.
description The coupon description. This will be displayed to the customers after the coupon validation.
percentage The discount percentage. Should be an interger between 1 and 100. You should set the percentage or the amount, but not both.
amount Flat discount amount as a string with dollars and (optionally) cents, i.e. “10.00” for $10.00. You should set the percentage or the amount, but not both.
allow_negative_balance Boolean. If true, credits will carry forward to next billing. Otherwise discount may not exceed total of the charges.
recurring Boolean. If true, the discount will be applied at signup and every renewal (for the number of renewals given by duration_period_count). Otherwise, discount will be applied only at signup.
duration_period_count Integer. Number of renewals the coupon is good for. Recurring should be set to true. Setting recurring to true and leaving this blank indicates that the coupon applies indefinitely.
coupon_end_date Coupon ending date. If set, the coupon will expire at the end of the day on this date.
product_family_id. The ID of the product family to which the coupon belongs. The coupon can be applied only to products in this product family.

Creating a Coupon via the API

To create a coupon, simply POST the coupon information to the correct URL endpoint.

Create

URL: https://<subdomain>.chargify.com/coupons.<format>
Method: POST
Required Parameters: Coupon parameters
Response: The created coupon
Usage Examples:
XML example
JSON example

XML Create Coupon Example


      <?xml version="1.0" encoding="UTF-8"?>
        <coupon>
          <name>15% off</name>
          <code>15OFF</code>
          <description>15% off for life</description>
          <percentage>15</percentage>
          <allow_negative_balance>false</allow_negative_balance>
          <recurring>false</recurring>
          <end_date>2012-08-29T12:00:00-04:00</end_date>
          <product_family_id>2</product_family_id>
        </coupon>

JSON Create Coupon Example


    {
       "coupon" :{
           "name": "15% off",
           "code": "15OFF",
           "description": "15% off for life",
           "percentage": "15",
           "allow_negative_balance": "false",
           "recurring": "false",
           "end_date": "2012-08-29T12:00:00-04:00",
           "product_family_id": "2"
      }
    }

Retrieving a Coupon via the API

You can retrieve a coupon via the API with the show method. You must identify the coupon in this call by the id parameter that Chargify assigns. If instead you would like to find a coupon using a coupon code, see the Coupon Find method.

Show

URL: https://<subdomain>.chargify.com/coupons/<coupon_id>.<format>
Method: GET
Required Parameters: coupon_id
Response: The coupon

Updating a Coupon via the API

You can update a coupon via the API with a PUT request to the resource endpoint.

Update

URL: https://<subdomain>.chargify.com/coupons/<coupon_id>.<format>
Method: PUT
Required Parameters: Coupon params, including coupon_id
Response: The updated coupon

Archiving a Coupon via the API

You can archive a coupon via the API with the archive method. Archiving makes that coupon unavailable for future use, but allows it to remain attached and functional on existing subscriptions that are using it.

Validating a Coupon via the API

You can verify if an specific coupon code is valid using the validate method. This method is useful for validating coupon codes that are entered by a customer. If the coupon is found and is valid, the coupon will be returned with a 200 status code.

Validate

URL: https://<subdomain>.chargify.com/coupons/validate.<format>?code=<coupon_code>
Method: GET
Required Parameters: coupon_id or coupon_code
Response: If the coupon is invalid, the status code will be 404 and the response will say why its invalid. If it’s valid the status code will be 200 and the coupon will be returned. The following reasons for invalidity are supported:

Coupon not found
Coupon is invalid
Coupon expired

If you have more than one product family and if the coupon you are validating does not belong to the first product family in your site, then you will need to specify (either in the url or as a query string param) the product family id.

Eg.

https://<subdomain>.chargify.com/product_families/<product_family_id>/coupons/validate.<format>?code=<coupon_code>

https://<subdomain>.chargify.com/coupons/validate.<format>?code=<coupon_code>&product_family_id=1

Finding a Coupon via the API

You can search for a coupon via the API with the find method. By passing a code parameter, the find will attempt to locate a coupon that matches that code. If no coupon is found, a 404 is returned.

Find

URL: https://<subdomain>.chargify.com/coupons/find.<format>
Method: GET
Required Parameters: code
Response: The coupon

If you have more than one product family and if the coupon you are trying to find does not belong to the first product family in your site, then you will need to specify (either in the url or as a query string param) the product family id.

Eg.

https://<subdomain>.chargify.com/product_families/<product_family_id>/coupons/find.<format>?code=<coupon_code>

https://<subdomain>.chargify.com/coupons/find.<format>?code=<coupon_code>&product_family_id=1

Coupon Usage

You can get more information about an specific coupon usage, which consists of the following data points, per product:

Number of signups using coupon
Total amount of savings achieved
Total revenue received from subscriptions using the coupon

Usage

URL: https://<subdomain>.chargify.com/coupons/<coupon_id>/usage.<format>_
Method: GET
Required Parameters: coupon_id
Response: Details about the coupon usage as an array of data hashes, one per product. Example json:

[
  {
    "name":"Basic",    // Product Name
    "id":3,            // Product ID
    "revenue":48.0,    // Revenue from subscriptions that used coupon
    "signups":1,       // Number of signups that used coupon
    "savings":12.00    // Savings given by the coupon for this product
  },
  {
    "name":"Pro",
    "id":4,
    "revenue":0.0,
    "signups":0,
    "savings":0.0
  }
]

Creating a Subscription with a Coupon via the API

To apply a coupon to a subscription, simply pass a coupon_code parameter along with the usual Subscription parameters.

Create

URL: https://<subdomain>.chargify.com/subscriptions.<format>
Method: POST
Required Parameters: Subscription parameters + coupon_code
Response: The created subscription
Usage Examples:
XML example
JSON example

XML Create Subscription with Coupon Example


Scenario: Create a subscription successfully with a coupon
  Given I have 1 product
  And I have a $5 off coupon with the code "EARLYBIRD"
  And I have this xml subscription data
    """
      <?xml version="1.0" encoding="UTF-8"?>
      <subscription>
        <product_handle>[@product.handle]</product_handle>
        <customer_attributes>
          <first_name>Joe</first_name>
          <last_name>Blow</last_name>
          <email>joe@example.com</email>
        </customer_attributes>
        <credit_card_attributes>
          <full_number>1</full_number>
          <expiration_month>10</expiration_month>
          <expiration_year>2020</expiration_year>
        </credit_card_attributes>
        <coupon_code>EARLYBIRD</coupon_code>
      </subscription>
    """
  When I send a POST request with the xml data to https://[@subdomain].chargify.com/subscriptions.xml
  Then the response status should be "201 Created"
  And I should have 1 subscription
  And the subscription should have 1 coupon
  And the coupon should have been applied

JSON Create Subscription with Coupon Example


Scenario: Create a subscription successfully with a coupon
  Given I have 1 product
  And I have a $5 off coupon with the code "EARLYBIRD"
  And I have this json subscription data
    """
    {"subscription":{
      "product_handle":"[@product.handle]",
      "customer_attributes":{
        "first_name":"Joe",
        "last_name":"Blow",
        "email":"joe@example.com"
      },
      "credit_card_attributes":{
        "full_number":"1",
        "expiration_month":"10",
        "expiration_year":"2020"
      },
      "coupon_code":"EARLYBIRD"
    }}
    """
  When I send a POST request with the json data to https://[@subdomain].chargify.com/subscriptions.json
  Then the response status should be "201 Created"
  And I should have 1 subscription
  And the subscription should have 1 coupon
  And the coupon should have been applied

Adding and Removing a Coupon to an existing subscription

You can also add or remove a Coupon from an existing subscription using the API. To do that, you should have a valid coupon code and a subscription id.

Add

URL: https://<subdomain>.chargify.com/subscriptions/<subscription_id>/add_coupon.<format>?code=<coupon_code>
Method: POST
Required Parameters: subscription_id, coupon_code
Response: If the coupon is successfully applied, the subscription object will be returned. Otherwise, a ‘Coupon is invalid’ error will be returned.

Remove

URL: https://<subdomain>.chargify.com/subscriptions/<subscription_id>/remove_coupon.<format>?code=<coupon_code>
Method: DELETE
Required Parameters: subscription_id, coupon_code
Response: If the coupon is successfully removed, the subscription object will be returned. Otherwise, a ‘402 Uprocessable Entity’ error will be returned.

Next page: API: Credits
Previous page: API: Components

API: Coupons

URI/Method

Coupon Input Attributes

Creating a Coupon via the API

Create

XML Create Coupon Example

JSON Create Coupon Example

Retrieving a Coupon via the API

Show

Updating a Coupon via the API

Update

Archiving a Coupon via the API

Archive

Validating a Coupon via the API

Validate

Finding a Coupon via the API

Find

Coupon Usage

Usage

Creating a Subscription with a Coupon via the API

Create

XML Create Subscription with Coupon Example

JSON Create Subscription with Coupon Example

Adding and Removing a Coupon to an existing subscription

Add

Remove

Features

Resources

Community

Chargify