Developer | Promotion API

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

Authentication

You need to include your API key with each request, as a header or a parameter. Please refer to the Authentication page for details.

List Promotions

To list all promotional coupon codes in your account use:


			https://www.supersaas.com/api/promotions.json?account=<account_name>&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
Parameter	Value
`api_key`	The 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_name`	Account name (not your email address)

To retrieve information about a single coupon code use:


			https://www.supersaas.com/api/promotions.json?id=<promotion_code>&account=<account_name>&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
Parameter	Value
`code`	The coupon code
`description`	The description text, if any
`usage`	The 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=<account_name>&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
Parameter	Value
`id`	New promotion code that you want to create
`api_key`	The 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_name`	Account name
`template_code`	The promotion code that you want to duplicate