Basic Connectivity Options

Retailers can be connected to accelerators in two ways: as separate but connected "external accounts" or as sub-accounts within the accelerator account when they choose not to create an account with The Coupon Bureau and instead rely on an accelerator to provide a completely managed service.

This article discusses securing access to the Coupon Bureau’s APIs for retailers and accelerators in each connection scenario. It explains the best practices of using JWT tokens derived from the API key and secret and how to configure the API key directly at the POS system. It also highlighted that hardcoding the API key and secret directly in the Point of Sale (POS) system and making API calls directly from the POS can be a dangerous approach and should be avoided.

Finally, this article includes instructions for both.

External Account Connectivity

In The Coupon Bureau, retailers create an account referred to as an “External Retailer” account. These retailers have access to redemption API and can directly redeem without an accelerator.

As an External Retailer, you can give access to an accelerator to redeem coupons on your behalf while still wanting to pull reports from The Coupon Bureau. A typical setup looks like this:

As an External Retailer, you have control over the link between your account and the Accelerator, and the Accelerator can redeem coupons as long as the link exists. If you choose to remove the link, the Accelerator will no longer be able to redeem coupons on your behalf.

For the redemption process to occur, the point-of-sale system at the retailer’s location must establish a secure connection with the Accelerator’s cloud. The Accelerator will then identify the retailer and redeem the code through The Coupon Bureau’s/retailer/redeem API. During the redemption process, the Accelerator must provide the correct retailer identity (retailer_email_domain) to The Coupon Bureau platform so that the redemption can be appropriately attributed to the right retailer.

curl -X POST 'https://api.try.thecouponbureau.org/retailer/redeem' \
-H 'Content-Type: application/json' \
-H 'x-api-key: ACCELERATOR_ACCESS_KEY' \
-H 'x-access-token: ACCELERATOR_ACCESS_TOKEN' \
--data '{"gs1s":["Serialized GS1", "retailer_email_domain": "example.com"]}'

Note: It is a best practice to keep your API key and secret private and not share them with other entities, as they are used to secure access to the Coupon Bureau APIs using JWT tokens. This helps to ensure that only authorized users and applications can access the APIs and perform actions on your behalf. Additionally, it is important to rotate your API keys and secrets regularly to maintain the security of your integration.

Internal Retailers (sub-retailers)

It is possible for retailers to choose not to create an account with The Coupon Bureau and instead rely on an accelerator to provide a completely managed service for them. In this case, the retailers would not have access to the Coupon Bureau’s platform and would not have login information or API keys to access the platform.

It is important to keep in mind that in this scenario, the retailer will not have direct access to the platform, so it will be more challenging to have real-time data. It will depend on the Accelerator to provide the reports and the data access.

A typical setup looks like this when an accelerator is connected to internal and external retailers.

An accelerator has complete control over internal retailers and has the flexibility to use both approaches to secure access to the Coupon Bureau’s APIs.

Approach 1: When the Point of Sale (POS) system is connected to the Accelerator’s cloud, the cloud can make API calls to the Coupon Bureau’s platform on behalf of the internal retailer. In this approach, you must use an accelerator redemption API call to pass the retailer’s identity during redemption. This approach requires you to configure the API key and secret in your middleware cloud, thus eliminating the issue of the API key being compromised.

curl -X POST 'https://api.try.thecouponbureau.org/retailer/redeem' \
-H 'Content-Type: application/json' \
-H 'x-api-key: ACCELERATOR_ACCESS_KEY' \
-H 'x-access-token: ACCELERATOR_ACCESS_TOKEN' \
--data '{"gs1s":["Serialized GS1", "retailer_email_domain": "example.com"]}'

Approach 2: The Accelerator can configure retailer-specific API keys in the POS system. This approach allows the internal retailer direct access to the Coupon Bureau’s APIs and eliminates the need for cloud-based middleware. This improves the redemption API call latency. This approach requires you to create internal retailer-specific API keys and configure those in the POS system. In this approach, you are not using your own key but the retailer-specific keys.

curl -X POST 'https://api.try.thecouponbureau.org/retailer/redeem' \
-H 'Content-Type: application/json' \
-H 'x-api-key: INTERNAL_RETAILER_ACCESS_KEY' \
-H 'x-access-token: INTERNAL_RETAILER_ACCESS_TOKEN' \
--data '{"gs1s":["Serialized GS1"]}'

As you can create an API key for a specific internal retailer, that internal retailer POS could not use that key to do something on behalf of another internal retailer. This approach allows the Accelerator to better control and track the keys’ usage and prevent misuse.

Instructions

External account:
To achieve separate but connected accounts, a retailer must follow our typical account setup process, instructions here. This arrangement allows a retailer to maintain their own account, control their partner connections, and always have direct access to their coupon redemption data.

Sub-account:
Creating a “sub-account” allows the Accelerator partner to set up the retailer within their accelerator account, which eliminated the need for the retailer from setting up and maintaining their own account.

Locate My Retailers in your Settings

Add Retailer using “+ADD RETAILER” in the upper right-hand corner and then use Action to set the API key and optionally, Set Clearinghouse.