API: Coupon Subcodes

Coupon subcodes can be administered in the Admin Interface or via the API.

URI/Method

Resource/URI GET POST PUT DELETE
Coupon Subcodes
/coupons/:coupon_id/codes
List all coupon subcodes
Coupon Subcodes
/coupons/:coupon_id/codes
Create new coupon subcodes
Coupon Subcodes
/coupons/:coupon_id/codes
Update coupon subcodes
Coupon Subcodes
/coupons/:coupon_id/codes/:id
Delete a coupon subcode

Coupon Input Attributes

When creating a coupon subcode, you must specify a coupon to attach it to using the coupon_id. Valid coupon subcodes are all capital letters, contain only letters and numbers, and do not have any spaces. Lowercase letters will be capitalized before the subcode is created.

Creating a Coupon Subcode via the API

To create a coupon subcode, simply POST an array of subcodes to the correct URL endpoint.

Create

URL: https://<subdomain>.chargify.com/coupons/:coupon_id/codes.<format>
Method: POST
Required Parameters: An array of valid coupon subcodes
Response: The created subcodes, subcodes that were not created because they already exist, and any subcodes not created because they are invalid.
Usage Examples:
XML example
JSON example

XML Create Coupon Subcodes Example

<?xml version="1.0" encoding="UTF-8"?>
  <codes type="array">
    <code>15OFF</code>
    <code>20OFF</code>
    <code>50 OFF</code>
  </codes>

Example Response:

 <?xml version="1.0" encoding="UTF-8"?>
 <codes>
   <created_codes type="array">
     <created_code>15OFF</created_code>
     <created_code>20OFF</created_code>
   </created_codes>
   <duplicate_codes type="array"/>
   <invalid_codes type="array">
     <invalid_code>50 OFF</invalid_code>
   </invalid_codes>
 </codes>

JSON Create Coupon Subcodes Example

{
  codes: ["15OFF", "20OFF", "50 OFF"]
 }

Example response:

{
  "created_codes"   => ["15OFF", "20OFF"],
  "duplicate_codes" => [],
  "invalid_codes"   => ["50 OFF"]
}

Retrieving Coupon Subcodes via the API

You can retrieve all the coupon subcodes for a given coupon via the API.

List

URL: https://<subdomain>.chargify.com/coupons/<coupon_id>/codes.<format>
Method: GET
Required Parameters: coupon_id
Optional Parameters: page, per_page (default of 20)
Response: A collection of coupon subcodes

XML Example Response

 <?xml version="1.0" encoding="UTF-8"?>
 <codes type="array">
   <code>15OFF</code>
   <code>20OFF</code>
 </codes>

JSON Example Response

{
  codes: ["15OFF", "20OFF"]
 }

Updating Coupon Subcodes via the API

You can update the subcodes for a given coupon via the API with a PUT request to the resource endpoint. Note that all current subcodes for that coupon will be deleted first, and replaced with the list of subcodes sent to this endpoint.

Update

URL: https://<subdomain>.chargify.com/coupons/<coupon_id>/codes.<format>
Method: PUT
Required Parameters: coupon_id, and an array of new coupon subcodes
Response: The created subcodes, subcodes that were not created because they already exist, and any subcodes not created because they are invalid.
Usage Examples:
XML example
JSON example

XML Update Coupon Subcodes Example

<?xml version="1.0" encoding="UTF-8"?>
  <codes type="array">
    <code>15OFF</code>
    <code>20OFF</code>
    <code>50 OFF</code>
  </codes>

Example Response:

 <?xml version="1.0" encoding="UTF-8"?>
 <codes>
   <created_codes type="array">
     <created_code>15OFF</created_code>
     <created_code>20OFF</created_code>
   </created_codes>
   <duplicate_codes type="array"/>
   <invalid_codes type="array">
     <invalid_code>50 OFF</invalid_code>
   </invalid_codes>
 </codes>

JSON Update Coupon Subcodes Example

{
  codes: ["15OFF", "20OFF", "50 OFF"]
 }

Example response:

{
  "created_codes"   => ["15OFF", "20OFF"],
  "duplicate_codes" => [],
  "invalid_codes"   => ["50 OFF"]
}

Deleting Coupon Subcodes via the API

URL: https://<subdomain>.chargify.com/coupons/<coupon_id>/codes/<subcode>.<format>
Method: DELETE
Required Parameters: coupon_id, and coupon subcode
Response: If the coupon subcode is successfully removed, a ‘200’ response code will be returned. Otherwise, a ‘404’ error will be returned.

Note: If you are using any of the allowed special characters (“%”, “@”, “+”, “-”, “_”, and “.”), you must encode them for use in the URL.

Special character Encoding
% %25
@ %40
+ %2B
%2D
_ %5F
. %2E

Given a coupon with an id of 567, and a coupon subcode of 20OFF, the URL to delete this coupon subcode would be: @https://<subdomain>.chargify.com/coupons/567/codes/20OFF.<format>

Or if the coupon subcode is 20%OFF, the URL to delete this coupon subcode would be: @https://<subdomain>.chargify.com/coupons/567/codes/20%25OFF.<format>