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.

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. 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.

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.

Internal account (Sub-retailer):
Creating a “sub-account” allows the Accelerator partner to set up the retailer within their accelerator account, which eliminates the need for the retailer to set up and maintain their own account.

1. Locate My Retailers in your Settings

2. Add Retailer using “+ADD RETAILER” in the upper right-hand corner and add the Retailer Name in the Name field and the Retailer Name with no spaces in the Identifier field. 
   • Name: Nicole's Food Store 
   • Identifier: Nicolesfoodstore

        Note: When adding Retailers, only one sub-retailer needs to be added per banner. 

2.  Use Action to set the API key and optionally, Set Clearinghouse.