API: Coupons

A Coupon resource describes the attributes of a promotional code that self-service advertisers to redeem in the ad store in return for a discount during checkout.

Supported Methods

List coupons

• URL - http://<subdomain>.trafficspaces.com/resources/coupons/
• Method - GET
• Parameters -
  • page - (unsigned, optional) an integer value that specifies which page of results to fetch, starting at 1. Default: 1. Minimum: 1.
  • pagesize - (unsigned, optional) how many results to fetch in each request. Default: 25. Maximum: 100
• Response
  • Status - 200, if successful.
  • Body - A collection of up to pagesize coupons in the requested format

Read a coupon

• URL - http://<subdomain>.trafficspaces.com/resources/coupons/<coupon_id>.<format>
• Method - GET
• Parameters - None
• Response
  • Status - 200, if successful.
  • Body - The requested coupon in the requested format

Create a new coupon

• URL - http://<subdomain>.trafficspaces.com/resources/coupons/
• Method - POST
• Parameters - XML or JSON data. See the Attributes below
• Response
  • Status - 201, if successful.
  • Body - The created coupon in the requested format
  • Headers
    • Location - A relative URL for the newly created coupons

Update an existing coupon

• URL - http://<subdomain>.trafficspaces.com/resources/coupons/<coupon_id>.<format>
• Method - PUT
• Parameters - XML or JSON data. See the Attributes below
• Response
  • Status - 200, if successful.
  • Body - The updated coupon in the requested format

Delete an existing coupon

• URL - http://<subdomain>.trafficspaces.com/resources/coupons/<coupon_id>.<format>
• Method - DELETE
• Parameters - None
• Response
  • Status - 200, if successful.

Attributes

• coupon - (object, rwa)
  • id - (string, r) the alphanumeric unique identifier
  • name - (string, rwa) the display name in the ad store.
  • code - (string, rwa) the alphanumeric promo code
  • type - (string, r) the code that describes the way coupon's discount is expressed. Valid values include
    • absolute - the discount is expressed as a discrete monetary value
    • relative - the discount is expressed as a percentage
  • base_value - (double, rwa, optional) the minimum value of the principal upon which the discount is applied. Defaults to 0 which means it has no minimum.
  • discount_value - (double, rwa) the face value of the discount that is applied on the base_value
  • cumulative_discount - (double, r) the cumulative value of the discounts that have been redeemed with the coupon
  • maximum_cumulative_discount - (double, rwa, optional) the maximum cumulative value of the discounts that have been redeemed with the coupon before it expires automatically. Defaults to 0 which means it has no maximum.
  • cumulative_uses - (double, r) the cumulative number of times the coupon can be used
  • maximum_cumulative_uses - (double, rwa, optional) the maximum cumulative number of times the coupon can be used before it expires automatically. Defaults to 0 which means it has no maximum.
  • realm - (string, r) the subdomain name of the ad store
  • creation_date - (datetime, r) the date on which the coupon was created.
  • last_modified_date - (datetime, r) the date on which the coupon was last modified.
  • expiration_date - (datetime, rwa, optional) the date on which the coupon expires. If it is not specified, the coupon will not expire.
  • linked_user - (object, rw)
    • id - (string, rw) the alphanumeric unique identifier of the user that created the coupon
    • name - (string, r) the username of the user that created the coupon

Examples

Coupon - JSON

{
    "id": "161c1e2c010f1a6e",
    "name": "Test Coupon 1 - No Expiration",
    "code": "TEST1",
    "type": "absolute",
    "base_value": 0
    "discount_value": 45.0,
    "cumulative_discount": 0,
    "maximum_cumulative_discount": 45.0,
    "cumulative_uses": 0,
    "maximum_cumulative_uses": 0,
    "realm": "fresh",
    "creation_date": "2010-06-30T17:13:42",
    "last_modified_date": "2010-06-30T17:13:42",
    "linked_user": {
        "id": "0937111d0e6b33150a0e6f66",
        "name": "admin@mywebsite.com"
    }
}

Coupon - XML

<?xml version="1.0" encoding="UTF-8"?>
<coupon>
    <id>0937111d0e6b3c22</id>
    <name>Test Coupon 2</name>
    <code>TEST2</code>
    <type>relative</type>
    <base_value>200.0</base_value>
    <discount_value>10.0</discount_value>
    <cumulative_discount>0.0</cumulative_discount>
    <maximum_cumulative_discount>0.0</maximum_cumulative_discount>
    <cumulative_uses>0</cumulative_uses>
    <maximum_cumulative_uses>0</maximum_cumulative_uses>
    <realm>fresh</realm>
    <creation_date>2009-04-01T22:19:11</creation_date>
    <last_modified_date>2009-04-01T22:19:11</last_modified_date>
    <expiration_date>2009-04-30T00:00:00</expiration_date>
    <linked_user>
        <id>0937111d0e6b33150a0e6f66</id>
        <name>admin@mywebsite.com</name>
    </linked_user>
</coupon>