Rewards API

The Rewards API allows you to reward your customers with products that are fulfilled by Amazon. The API is supported for apps (Android, IOS, and FireOS) and websites.

This guide provides instructions for the Rewards APIs along with examples of how to use the APIs.

Overview

The following are the high-level steps for using the Rewards APIs:

  1. Use the Moments Console to register the app and configure the rewards. See Configure Your App.
  2. If the campaign is a challenge , call the getRewardInfo endpoint to get the content to notify the users that you want to target for this campaign.
  3. Your rule engine must evaluate whether the user qualifies for the campaign. If a user qualifies, you can call the getReward endpoint to consume a reward and send the reward URL to the user.

The following workflow map shows the high-level interactions.

API Endpoints

For details about the API endpoints, see the API Endpoint Specification. These endpoints are specified in OpenAPI format, which provides an interactive API explorer in which you can try out sample API calls.

There are two endpoints in the Rewards API:

The two endpoints use the same request parameters. The main difference between them is that the GetReward endpoint consumes a reward and the GetRewardInfo endpoint returns information about the reward but does not consume the reward.

API Authorization

The Rewards API uses an API key passed in the header to authorize requests.

x-api-key: "API KEY"

You can obtain the API Key for your app in the Registration Details information in the Moments Console.

API Throttling

  1. Each app that you register receives a unique API key that you include in each API call.
  2. For each API key, the API sets a default limit of 5 calls per second (for any combination of getRewardInfo and getReward calls).
  3. If the traffic from an API Key exceeds 5 calls per second, we will throttle the flow by sending an error response to each excess API call.
  4. We recommend that you implement logic to handle API throttling. If an API call is throttled:
    • After a delay, retry the API call.
    • Limit the number of retries.

Note: If you do not set a delay and do not restrict the number of retries, the number of retry requests may cause the throttling to get worse.

API Timeout

The Moments service sets a 10-second timeout for each Rewards API request. You must set a longer timeout in your server implementation, to ensure that you always get a response from the Moments service (a success response, error response or a timeout).

If your server times out before the Moments service, you may miss the success response from a getReward call. In this situation, Moments will charge you for the reward, but your app is unaware of the reward and will never offer it to the user.

We recommend that you implement code to recover from an API timeout, with logic similar to the API throttling logic described above.

API Requests in Various Languages

The following tabs show how to call the endpoints in various languages.

cURL

curl -X POST -H "x-api-key: kE2xi2OgUa7jfijmsd0jQ74aJntJwUEW2EU8LUsi" -H "Content-Type: application/json; charset=UTF-8" -d "{
	'appId': 'DEMO1',
	'momentId':'MomentsReward',
	'deviceType' : 'Android',
	'campaignId' : 'DEMOCAMP1',
	'rewardGroupId': 'US'
}" "https://dnxr7vm27d.execute-api.us-east-1.amazonaws.com/prod/GetReward"

Java

String url = "https://dnxr7vm27d.execute-api.us-east-1.amazonaws.com/prod/GetReward";
URL obj = new URL(url);
HttpsURLConnection connection = (HttpsURLConnection) obj.openConnection();

connection.setRequestMethod("POST");
connection.setRequestProperty("Accept-Language", "UTF-8");
connection.setRequestProperty("Content-Type", "application/json");
connection.setRequestProperty("x-api-key", "kE2xi2OgUa7jfijmsd0jQ74aJntJwUEW2EU8LUsi");

connection.setDoOutput(true);
OutputStreamWriter outputStreamWriter = new OutputStreamWriter(connection.getOutputStream());
JSONObject json = new JSONObject();
json.put("appId", "DEMO1");
json.put("momentId", "MomentsReward");
json.put("deviceType", "Android");
json.put("campaignId", "DEMOCAMP1");
json.put("rewardGroupId", "US");

outputStreamWriter.write(json.toString());
outputStreamWriter.flush();

int responseCode = connection.getResponseCode();
System.out.println("\nSending 'POST' request to URL : " + url);
System.out.println("Post parameters : " + urlParameters);
System.out.println("Response Code : " + responseCode);

BufferedReader bufferedReader = new BufferedReader(new InputStreamReader(connection.getInputStream()));
String output;
StringBuffer response = new StringBuffer();

while ((output = bufferedReader.readLine()) != null) {
 response.append(output);
}
bufferedReader.close();

System.out.println(response.toString());

Python

# Requests lib should be installed: http://docs.python-requests.org/en/master/user/install/#install
import requests

API_ENDPOINT = "https://dnxr7vm27d.execute-api.us-east-1.amazonaws.com/prod/GetReward"
API_KEY = "kE2xi2OgUa7jfijmsd0jQ74aJntJwUEW2EU8LUsi" # Your API key here
headers = {"x-api-key": API_KEY, "Content-Type": "application/json"} # Headers
# Data to be sent to API
data = {
    'appId': 'DEMO1',
    'momentId': 'MomentsReward',
    'deviceType': 'Android',
    'campaignId': 'DEMOCAMP1',
    'rewardGroupId': 'US'
}
# Sending post request and saving response as response object
r = requests.post(url = API_ENDPOINT, headers=headers, json = data)
# extracting response text
response = r.text
print("headers: %s"%headers)
print("data: %s"%data)
print("The response is: %s"%response)

Node.js

var options = {
    url: 'https://dnxr7vm27d.execute-api.us-east-1.amazonaws.com/prod/GetRewardInfo',
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        'x-api-key': 'kE2xi2OgUa7jfijmsd0jQ74aJntJwUEW2EU8LUsi'
    }
};
var req = http.request(options, function(res) {
    console.log('Status:' + res.statusCode);
    console.log('Headers: ' + JSON.stringify(res.headers));
    res.on('data', function(body) {
        console.log('Body:' + body);
    });
});

req.on('error', function(e) {
    console.log('problem with request: ' + e.message);
});

// write data to request body
req.write('{"x-api-key":"12345", "Content-Type":"application/json", "appId":"DEMO1","momentId":"MomentsReward","deviceType":'
    Android ','
    campaignId ':"DEMOCAMP1","rewardGroupId":"US"}');
req.end();

If you're calling the Rewards APIs in a language not shown, you will need to determine the API request format for that language.

Error Messages

If the Moments service cannot complete the API request successfully, the rewardNotificationText field contains a text message to explain the error.
Note that these error responses use HTTP status code 200. Possible error messages include:

  • "Invalid Credential"
  • "Campaign is not active (Active from %s to %s)."
  • "Invalid Campaign."
  • "No Campaign is found that matches appId = %s, campaignId = %s, momentId = %s and rewardGroupId = %s"
  • "No Available Reward Found."
  • "Campaign Monthly Limit Reached."

Test Account

To explore the Rewards APIs, you can use the following test account and configuration. (You use most of these parameters in the body request when calling the endpoints.)

In this demo, there is one campaign (DEMOCAMP1) defined for the app (DEMO1). In the campaign, the configuration defines one moment (MomentsReward) for the Android device type. There is one reward group available for this moment. This reward group has 5 available rewards, which makes a total of 5 rewards for this campaign.

Field Value
DEV ID MOMENTS
(This value isn't used in the endpoint requests; it's used behind the scenes to group apps by developer)
API KEY kE2xi2OgUa7jfijmsd0jQ74aJntJwUEW2EU8LUsi
appId DEMO1
campaignId DEMOCAMP1
deviceType Android
rewardGroupId US
momentId MomentsReward

During your testing and development, if you consume all of the rewards in the test account, you can reset the rewards back to 5 by submitting a GET request to https://at0xry1l42.execute-api.us-east-1.amazonaws.com/prod with the same API key. For example, you can submit this via your terminal with cURL:

curl -H "x-api-key: kE2xi2OgUa7jfijmsd0jQ74aJntJwUEW2EU8LUsi" "https://at0xry1l42.execute-api.us-east-1.amazonaws.com/prod/"

The response will be null. However, the rewards will be reset.