Back to index

Promotion API

The Promotion API allows you to create coupon codes for promotions and retrieve usage information about existing coupon codes.

Authentication

Please refer to the Authentication Page.

List Promotions

To list promotional coupon codes in your account use:

https://www.supersaas.com/api/promotions.json?account=&api_key=your_api_key

The table below describes the possible input values that can be used as URL parameters in this API:

Input Values
ParameterValue
api_keyThe administrator API Key for the account the schedule belongs too. You can also omit this field and use HTTP Basic Authentication or an MD5 hash instead.
limit(Optional) Indicate the maximum number of results you want returned. For large requests you can make multiple requests and add an offset parameter to page through the results
account_nameAccount name

To retrieve information about a single coupon code use:

https://www.supersaas.com/api/promotions.json?id=<promotion_code>&account=&api_key=your_api_key

If the request is successful then you can expect the following result in JSON when you retrieve multiple promotions:

[
  {
    "code": "promo-code-1",
    "description": "...",
    "usage": 0
  },
  {
    "code": "promo-code-2",
    "description": "...",
    "usage": 10
  }
]

You’ll see the following JSON when you retrieve a single promotion:

{
  "code": "promo-code-1",
  "description": "...",
  "usage": 0
}
The table below describes the meaning of the fields that can be found in the JSON file.
Output Values
ParameterValue
codeThe coupon code
descriptionThe description text, if any
usageThe number of times the code has been used

The API returns the result in JSON format by default. You can force the result to be returned in XML format by replacing promotions in the URLs above with promotions.xml.

Duplicate a promotion code

Duplicates the promotion with the provided coupon code. You would need to first create a coupon code with the desired characteristics on the Promotions screen. This code will act as a template for the newly created coupon code. The request should be formatted as follows:
POST https://www.supersaas.com/api/promotions.json?id=<promotion_code>&template_code=<template_code>&account=&api_key=your_api_key

The table below describes some possible input values that can be used as URL parameters in this API:

Input Values
ParameterValue
idNew promotion code that you want to create
api_keyThe administrator API Key for the account the schedule belongs too. You can also omit this field and use HTTP Basic Authentication or an MD5 hash instead.
account_nameAccount name
template_codeThe promotion code that you want to duplicate