Coupon API Specification

Overview

Rokt's Coupon API enables Rokt ads clients to seamlessly access and retrieve promotional coupon codes for use in their campaigns. Coupons are managed in the Rokt system, and can be administered upon customer conversion of a Rokt ad.

Authentication

Reach out to your Rokt account manager to create an API key to access Rokt’s Coupon API. The API leverages base64-encoded bearer auth. Your API keys carry many privileges, so be sure to keep them secure! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, and so forth.

API Reference

The Coupon API requires coupons tied to a Rokt Creative along with a Rokt Session ID for coupon administration. Session IDs are required in order to ensure at most once distribution of a given coupon code. If you’re unsure of your Account ID, reach out to your account manager. More details can be found in the Key Requirements section.

Endpoint URL	http://coupon-api.rokt.com/api/v1

Request

POST /accounts/{account_id}/creative/{creative_id}/session/{session_id}/allocate-coupon

Headers

Name	Value	Required	Description
Content-Type	application/json	Yes	N/A
Charset	utf-8	Yes	N/A
Authorization	Bearer base64(rokt-coupon-key:{secretValue})	Yes	Bearer authentication header, with the credential value being a base64 encoding of the string "rokt-coupon-key" and the secret value, joined by a colon

Parameters

Name	Required	Type	In	Description
accountId	Yes	String, up to 64 characters	Path	Rokt Account ID
creativeId	Yes	Long	Path	Rokt internal identifier for the creative that customer opted in to
sessionID	Yes	String, up to 64 characters	Path	Rokt Session ID, passed as part of traffic URL from the partner

Example Request

curl -X POST http://coupon-api.rokt.com/api/v1/accounts/3284705019915440561/creative/1/session/1/allocate-coupon \
-H "Content-Type: application/json" \
-H "Authorization: Bearer {YOUR_ENCODED_TOKEN}" \
-d '{}'

Example Response

{
  "couponId": "67c41952-55b5-4fca-8fe8-8da4116ded3e",
  "couponCode": "COUPON-CODE-475558",
  "accountId": "3284705019915440561",
}

Error Handling

Exception	HTTP Code	Cause	Resolution
AuthorizationHeaderMissing	401 Unauthorized	The Authorization header is missing in the request.	Ensure the request includes a valid Authorization header.
AuthenticationFailure	401 Unauthorized	Invalid API key, expired token, or incorrect credentials.	Ensure valid authentication credentials are provided.
InvalidAuthorizationHeaderFormat	401 Unauthorized	The Authorization header format is incorrect (e.g., missing Bearer or malformed token).	Ensure the header follows the correct format, e.g. Authorization:Bearer base64(rokt-coupon-key:{secretValue})
FailedToRetrieveSecrets	401 Unauthorized	The Authorization header format is invalid (the token is incorrect or missing from secrets).	Verify the Authorization header format.
InvalidToken	401 Unauthorized	The provided token is invalid, expired, or revoked.	Request a new token and ensure it is valid before use.
FailedToValidateCouponPayload	400 Bad Request	The coupon request payload contains invalid or missing fields.	Ensure all required fields are included and properly formatted before sending the request.
FailedToAllocateCoupon	500 Internal Server Error	The server encountered an issue while attempting to allocate a coupon.	This error occurred due to issues with the Coupon API or its underlying services. Contact Rokt Support channel.
NoCouponsRemaining	404 Not Found	There are no coupons left for this offer.	Contact your Rokt account manager to replenish the coupon list.

Key Requirements

To retrieve coupon codes from the Rokt Coupon API, the following parameters are essential:

• Account ID
• Creative ID
• Session ID

While your Account ID is a constant value, Rokt will provide Session ID and Creative ID to you via the creative destination URL. Details on how to do this are listed below.

Data flow for Advertiser Integration

1. Extract parameters from traffic URL: When a user is redirected to the Advertiser’s page, the traffic URL will include the required parameters. For example, the creative may have the following traffic URL: https://samplewebsite.com/download?sessionid=abcdef123456&creativeid=67890. Session ID is a UUID, while creative ID is a bigint.

2. Store parameters in local storage: Advertisers should parse the URL and store session ID and creative ID securely in the browser’s local storage, or alternate method of your choosing. See the following example code snippet for extraction and storage:

const urlParams = new URLSearchParams(window.location.search);
const sessionid = urlParams.get('sessionid');
const creativeid = urlParams.get('creativeid');

if (sessionid && creativeid) {
    localStorage.setItem('sessionid', sessionid);
    localStorage.setItem('creativeid', creativeid);
}

3. Pass stored parameters to the Rokt Coupon API: When calling the Rokt Coupon API, retrieve the stored parameters from local storage and include them in the API request body. See the following example code snippet for calling the API:

note

Account id, auth token, and other sensitive information should not be stored directly in code. This example is for demonstration purposes only.

// Extract parameters from the traffic URL
const urlParams = new URLSearchParams(window.location.search);
const sessionid = urlParams.get('sessionid');
const creativeid = urlParams.get('creativeid');
const accountid = 'YOUR_ACCOUNT_ID'; // Replace with your Rokt account ID

// Store parameters in local storage
if (sessionid && creativeid) {
    localStorage.setItem('sessionid', sessionid);
    localStorage.setItem('creativeid', creativeid);
}

// Retrieve and pass stored parameters in the API call
const storedSessionId = localStorage.getItem('sessionid');
const storedCreativeId = localStorage.getItem('creativeid');

if (storedSessionId && storedCreativeId && accountid) {
    // Construct the API URL dynamically with parameters in the path
    const apiUrl = `http://coupon-api.stage.rokt.com/api/v1/accounts/${accountid}/creative/${storedCreativeId}/session/${storedSessionId}/allocate-coupon`;
    
    fetch(apiUrl, {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json',
            'Authorization': `Bearer ${authToken}` // Replace authToken with your API Key
        },
        body: JSON.stringify({}) // Empty JSON body as required
    })
    .then(response => {
        if (!response.ok) {
            throw new Error(`HTTP error! status: ${response.status}`);
        }
        return response.json();
    })
    .then(data => {
        console.log('Coupon Code:', data.code);
    })
    .catch(error => console.error('Error:', error));
} else {
    console.error('Required parameters are missing.');
}