Manufacturer Getting Started Guide

Manufacturer APIs allow a manufacturer to deposit their own offers into TCB through their own internal systems. APIs are NOT required for a Manufacturer to connect to The Coupon Bureau, these APIs are designed specifically for partners who are looking to integrate these functions into your own system.

API functions include Master Offer File deposits, Authorized Partner authorization by account for Master Offer File management, and Provider authorization by Master Offer File or account for distribution.

Step #1 : Get Access Token

curl -X POST '{{API_SERVER}}/access_token' \
-H 'Content-Type: application/json' \
--data '{ 
    "access_key": "ACCESS_KEY", 
    "secret_key": "SECRET_KEY" 
}'

The Access Token will be valid for 24 hours. You should cache it and use the same access token for next 59 mins to call any other manufacturer APIs.

Step #2 : Create Master Offer File

curl -X POST '{{API_SERVER}}/manufacturer/base_gs1' \
-H 'Content-Type: application/json' \
-H 'x-access-key: ACCESS_KEY' \
-H 'x-access-token: ACCESS_TOKEN' \
--data '{
    "data":{
        "base_gs1":"8112010031493140188",
        "brand_id":"XYZ",
        "description":"50% off ",
        "campaign_start_time":"04/21/2020",
        "campaign_end_time":"04/30/2020",
        "redemption_start_time":"04/22/2020",
        "redemption_end_time":"04/30/2020",
        "total_circulation":"100",
        "primary_purchase_save_value":"1",
        "primary_purchase_requirements":"1",
        "primary_purchase_req_code":"1",
        "primary_purchase_gtins":[
            "294239749273","2390843209"
            ],
        "primary_purchase_family_code":"",
        "additional_purchase_rules_code":"",
        "second_purchase_requirements":"",
        "second_purchase_gs1_company_prefix":"",
        "second_purchase_req_code":"",
        "second_purchase_gtins":[
            ""
            ],
        "second_purchase_family_code":"",
        "third_purchase_requirements":"",
        "third_purchase_gs1_company_prefix":"",
        "third_purchase_req_code":"",
        "third_purchase_gtins":[
            ""
            ],
        "third_purchase_family_code":"",
        "gln":"",
        "save_value_code":"1",
        "applies_to_which_item":"",
        "store_coupon":"1",
        "donot_multiply_flag":""
    }
}'
    
        

Once the master offer file is created, you can use the below API call to manage the master offer files.
      Assign / Unassign provider for master offer file
      Delete master offer file

To get master offer file(s) created by you
      My master offer files
      Master offer file detail

Master offer file needs to be locked before a provider deposits a serialized data string. If the master offer file is editable (not locked), no one will be able to deposit a serialized data string under that master offer file.
      My master offer files
      Master offer file detail

Step #3.1 : Get all Providers connected to TCB

curl -X GET '{{API_SERVER}}/providers' \
-H 'Content-Type: application/json' \
-H 'x-access-key: ACCESS_KEY' \
-H 'x-access-token: ACCESS_TOKEN' 
      

This API response can be cached so that you can skip this step. Once you get the list of providers, you can select the desired providers (email_domain of the provider) from this list to authorize. Once the provider is authorized to distribute a master offer file, they can deposit the serialized GS1 of that master offer file.

Step #3.2 : Authorize provider(s) to allow master offer file distribution

curl -X POST '{{API_SERVER}}/manufacturer/base_gs1/<BASE_GS1>/toggle_provider' \
-H 'Content-Type: application/json' \
-H 'x-access-key: ACCESS_KEY' \
-H 'x-access-token: ACCESS_TOKEN' \
--data '{"email_domain":"qples.com"}'
       

You can call this API multiple times to authorize multiple providers. Once the provider is authorized, you can get the list of all authorized providers of a master offer file

      Get assigned providers of master offer file

Step #4.1 : Authorize a Authorized Partner

curl -X PUT '{{API_SERVER}}/manufacturer/toggle/manufacturer_agent' \
-H 'Content-Type: application/json' \
-H 'x-access-key: ACCESS_KEY' \
-H 'x-access-token: ACCESS_TOKEN' \
--data '{"email_domain":"qples.com"}'
        

You can call this API multiple times to authorize multiple Authorized Partners.
   To unauthorize a Authorized Partner use
      Call the same toggle api (/manufacturer/toggle/manufacturer_agent)

You can also get the list of all authorized Authorized Partners
      Get connected Authorized Partners

Step #4.2 : Give Brand Access to a Authorized Partner to create / manage master offer files and receive redemption data

curl -X PUT '{{API_SERVER}}/manufacturer/manufacturer_agents/:manufacturer_agent_email_domain/toggle_brand/:brand_internal_id' \
-H 'Content-Type: application/json' 
-H 'x-access-key: ACCESS_KEY' \
-H 'x-access-token: ACCESS_TOKEN' \
--data '{"access_type":"campaign_set"}'
        

You can call this API to authorize your brand to a manufacturer agent with proper access_type. access_type attribute value should be one of the below

• view_only: can view all the master offer files of the brand.
• campaign_set: can edit campaign detail of the master offer file of the brand.
• full_set: can edit complete master offer file of the brand.
• full_set_with_lock: can edit complete master offer and of the brand and can lock it to stop future update. Once the master offer file is locked, only campaign data (following attributes) can be edited.
  • description
  • campaign_start_time
  • campaign_end_time
  • redemption_start_time
  • redemption_end_time
  • total_circulation
  • primary_purchase_gtins
  • second_purchase_gtins
  • third_purchase_gtins

Authorized Partner Getting Started Guide

Authorized Partner APIs allow the ability to connect to the TCB from your internal systems so that you can directly deposit and manage an 8112 offer into a manufacturer’s TCB account and retrieve redemption data. APIs are NOT required for a Authorized Partner to perform your functions as they relate to The Coupon Bureau, these APIs are designed specifically for partners who are looking to integrate these functions into your own system.

Step #1 : Get Access Token

curl -X POST '{{API_SERVER}}/access_token' \
-H 'Content-Type: application/json' \
--data '{ 
    "access_key": "ACCESS_KEY", 
    "secret_key": "SECRET_KEY" 
}'

The Access Token will be valid for 24 hours. You should cache it and use the same access token for next 59 mins to call any other manufacturer APIs.

Step #2 : Get Connected Manufacturers

Required in step #3 where you will create master offer file on behalf of one manufacturer.

curl -X GET '{{API_SERVER}}/manufacturer_agent/manufacturers' \
-H 'Content-Type: application/json' \
-H 'x-access-key: ACCESS_KEY' \
-H 'x-access-token: ACCESS_TOKEN' 
        

You can cache the response of this API call as there will be no change in response until and unless another manufacturer authorizes the same Authorized Partner. Once you cache it, you can skip step #2 while creating a master offer file.

Step #3 : Create Master Offer File for a Manufacturer

curl -X POST '{{API_SERVER}}/manufacturer/base_gs1?email_domain=<MANUFACTURER_EMAIL_DOMAIN>' \
-H 'Content-Type: application/json' \
-H 'x-access-key: ACCESS_KEY' \
-H 'x-access-token: ACCESS_TOKEN' \
--data '{
    "data":{
        "base_gs1":"8112010031493140188",
        "brand_id":"XYZ",
        "description":"50% off ",
        "campaign_start_time":"04/21/2020",
        "campaign_end_time":"04/30/2020",
        "redemption_start_time":"04/22/2020",
        "redemption_end_time":"04/30/2020",
        "total_circulation":"100",
        "primary_purchase_save_value":"1",
        "primary_purchase_requirements":"1",
        "primary_purchase_req_code":"1",
        "primary_purchase_gtins":[
            "294239749273","2390843209"
            ],
        "primary_purchase_family_code":"",
        "additional_purchase_rules_code":"",
        "second_purchase_requirements":"",
        "second_purchase_gs1_company_prefix":"",
        "second_purchase_req_code":"",
        "second_purchase_gtins":[
            ""
            ],
        "second_purchase_family_code":"",
        "third_purchase_requirements":"",
        "third_purchase_gs1_company_prefix":"",
        "third_purchase_req_code":"",
        "third_purchase_gtins":[
            ""
            ],
        "third_purchase_family_code":"",
        "gln":"",
        "save_value_code":"1",
        "applies_to_which_item":"",
        "store_coupon":"1",
        "donot_multiply_flag":""
    }
}'
      

Once the master offer file is created, you can use the below API call to manage the master offer files.
To activate / deactivate / update a specific master offer file
      Activate / Deactive master offer file
      Assign / Unassign provider for master offer file
      Delete master offer file

To get master offer file(s) created by you
      My master offer files
      Master offer file detail

Step #4.1 : Get all Providers connected to TCB

curl -X GET '{{API_SERVER}}/providers' \
-H 'Content-Type: application/json' \
-H 'x-access-key: ACCESS_KEY' \
-H 'x-access-token: ACCESS_TOKEN' 
        

This API response can be cached so that you can skip this step. Once you get the list of providers, you can select the desired providers (email_domain of the provider) from this list to authorize. Once the provider is authorized to distribute a master offer file, they can deposit the serialized data string of that master offer file.

Step #4.2 : Authorize provider(s) to allow master offer file distribution

curl -X POST '{{API_SERVER}}/manufacturer/base_gs1/<BASE_GS1>/toggle_provider' \
-H 'Content-Type: application/json' \
-H 'x-access-key: ACCESS_KEY' \
-H 'x-access-token: ACCESS_TOKEN' \
--data '{"email_domain":"qples.com"}'
         

This API response can be cached so that you can skip this step. Once you get the list of providers, you can select the desired providers from this list to authorize. Once the provider is authorized to distribute a master offer file, they can deposit the serialized data string of that master offer file.

Step #4.3 : Authorize provider(s) to allow master offer file distribution

curl -X PUT '{{API_SERVER}}/manufacturer/toggle/manufacturer_agent' \
-H 'Content-Type: application/json' \
-H 'x-access-key: ACCESS_KEY' \
-H 'x-access-token: ACCESS_TOKEN' \
--data '{"email_domain":"qples.com"}'
          

You can call this API multiple times to authorize multiple Authorized Partners.
   To unauthorize a Authorized Partner use
      Call the same toggle api (/manufacturer/toggle/manufacturer_agent)

You can also get the list of all authorized Authorized Partners
      Get connected Authorized Partners

Provider Guide

Provider APIs allow a coupon provider to deposit/ delete a serialized data string (the serialized data string distributed to a consumer) into a manufacturer’s Master Offer File along with a series of other functions both required and optional to enhance the consumer experience. A provider will only be able to deposit serialized data strings into Master Offer Files of those manufacturers who have authorized them.

REQUIRED PROVIDER FUNCTIONS

The following required functions are used to meet industry standards and maintain consistent basic consumer experience functions across providers. All required functions will require proof of application before moving to the production server. Click here to view our Provider Guide to Universal Digital Coupons for more information about all provider functions.

• DEPOSIT SERIALIZED DATA STRINGS USING PROVIDER PREFIX (instructions below)
• DELETE SERIALIZED DATA STRINGS (instructions below)
• APPLY FETCHCODE TO CONSUMER EXPERIENCE (instructions below)
• ENABLE REDEMPTION / ROLLBACK WEBHOOK

Step #1 : Get Access Token

curl -X POST '{{API_SERVER}}/access_token' \
-H 'Content-Type: application/json' \
--data '{ 
    "access_key": "ACCESS_KEY", 
    "secret_key": "SECRET_KEY" 
}'

The Access Token will be valid for 24 hours. You should cache it and use the same access token for next 59 mins to call any other manufacturer APIs.

Step #2 : Get authorized master offer files.

Manufacturers / Manufacturer Agents will authorize provider to distribute master offer files. To get the list of all authorized master offer files, use My master offer files API

curl -X GET '{{API_SERVER}}/provider/base_gs1s' \
-H 'Content-Type: application/json' \
-H 'x-access-key: ACCESS_KEY' \
-H 'x-access-token: ACCESS_TOKEN' 
        

Step #3 : Generate your serialized data string

To accommodate multiple providers on a single master offer file, a “provider prefix” will be assigned and implemented as part of the serial number for each data string. This will resolve any potential duplication of serial numbers across providers. Follow the below process to generate your serialized data string

Master Offer File : 8112............VLIPROVIDER_PREFIXCONSUMER_IDENTIFIER

curl -X POST '{{API_SERVER}}/provider/serialization_prefix' \
-H 'Content-Type: application/json' \
-H 'x-access-key: ACCESS_KEY' \
-H 'x-access-token: ACCESS_TOKEN' 

Step #4 : Deposit serialized data string

curl -X POST '{{API_SERVER}}/provider/deposit' \
-H 'Content-Type: application/json' \
-H 'x-access-key: ACCESS_KEY' \
-H 'x-access-token: ACCESS_TOKEN' \
--data '{"gs1s":"<Comma Seperated GS1s>"}'

Apply Fetchcode to consumer experience

A Fetchcode is a code that is retrieved in real-time from a consumer’s phone in the event that the barcode cannot be scanned by a cashier. This code is valid for 5 minutes and will then expire. If the consumer still requires the use of a Fetchcode, another will immediately be provided.

curl -X GET '{{API_SERVER}}/provider/fetch_code/SERIALIZED_DATA_STRING' \
-H 'Content-Type: application/json' \
-H 'x-access-key: ACCESS_KEY' \
-H 'x-access-token: ACCESS_TOKEN'

Retailer Getting Started Guide

When an AI (8112) serialized data string is scanned at the POS, the POS makes an API request to POF with that serialized data string. The POF will then return the serialized data string with a status of “success” or “Failure” – if “success,” it will also send offer details. The POS then uses offer details from the API response to validate offer against basket data and apply the discount or send a rollback response if the discount cannot be applied.

There are two main components to consider:

Redeem:
This is the primary API endpoint for TCB Positive Offer File functionality. The retailer sends scanned data string(s) to POF, and POF responds with one or more data strings with "success" or "failure" for each.

      "success" means the serialized data string is available for redemption.
      "failure" means the data string was already redeemed or was in some other way invalid.

Whenever the API returns any "success" response, it is also marking the relevant data string as "redeemed", meaning the same data string cannot be used more than once.

      On "success", the data string will be accompanied with offer details
      On "failure", the failure reason will be returned per data string

Data strings will be use in the "rollback" scenario described below.

Rollback:
It may be necessary to "rollback" a data string in the event that purchase requirements are not met or a failed payment.

Example Flows
Retailer calls the TCB "redeem" API as they scan GS1s during the checkout process.

• In this flow, if a customer has 5 GS1s to scan, the retailer makes 5 calls to the TCB API during the checkout process. TCB will respond with applicable complete GS1s and "success" (valid) or "failure" (invalid) for each serialized GS1.
• Before payment is processed, the retailer must determine which valid complete GS1s are applicable to the customer's basket, and apply discounts appropriately.
• If any returned redeemed serialized GS1s are *not* applicable to the customer's basket, the TCB "rollback" API should be called for those un-applied serialized GS1s.
• If the payment fails for any reason and the transaction itself is rolled back, the TCB "rollback" API should be called for all serialized GS1s previously returned by the TCB "redeem" API, whether or not they were applied to the basket.

• In this flow, if a customer has 5 GS1s to scan, the retailer would scan GS1s during or at the end of the checkout process, and then make one single TCB "redeem" API call just before payment is processed. TCB will respond with a list of complete GS1s with "success" (valid) or "failure" (invalid) for each complete GS1.
• After the "redeem" API call is made, the retailer should determine which redeemed serialized GS1s are applicable to the customer's basket and apply the discounts.
• If any returned redeemed serialized GS1s are *not* applicable to the customer's basket, the TCB "rollback" API should be called for those un-applied complete GS1s.
• If the payment fails for any reason and the transaction itself is rolled back, the TCB "rollback" API should be called for all serialized GS1s previously returned by the TCB "redeem" API, whether or not they were applied to the basket.

Step #1 : Get Access Token

curl -X POST '{{API_SERVER}}/access_token' \
-H 'Content-Type: application/json' \
--data '{ 
    "access_key": "ACCESS_KEY", 
    "secret_key": "SECRET_KEY" 
}'

The Access Token will be valid for 24 hours. You should cache it and use the same access token for next 59 mins to call any other manufacturer APIs.

Step #2.1 : Redeem a Coupon

curl -X POST '{{API_SERVER}}/retailer/redeem' \
-H 'Content-Type: application/json' \
-H 'x-access-key: ACCESS_KEY' \
-H 'x-access-token: ACCESS_TOKEN' \
--data '{
    "gs1s":"<Comma seperated GS1s>",
    "selected_store":"<Store ID>"
  }'
        

How to handle "redeem" API responses

"redeem" API responses will be returned in a JSON array, with each item corresponding to a GS1 from the "gs1s" request array.
Response fields (per GS1 item):

  status -> "success" or "failure"
  newly_redeemed -> List of GS1s redeemed successfully
          {
            gs1: <GS1 redeemed>,
            master_offer_file: <Master offer file (base gs1) data string> Refer to master_offer_files mapping to get the purchase requirements
          }
  master_offer_files -> Master offer file purchase details


Example response for redeem

{
  "status": "success",
  "total_gs1s_processed": 3,
  "already_redeemed": [
      "811201777777754545412323432"
  ],
  "not_yet_live": [
      "8112013333333676767223234543"
  ],
  "newly_redeemed": [
      {
          "gs1": "811201777777754545412323433",
          "master_offer_file": "8112017777777545454"
      }
  ],
  "master_offer_files": {
      "8112017777777545454": {
          "primary_purchase_gtins": [
              "678987654323",
              " 876789876543"
          ],
          "second_purchase_gtins": [],
          "third_purchase_gtins": [],
          "primary_purchase_save_value": 100,
          "primary_purchase_requirements": 1,
          "primary_purchase_req_code": 0
      }
  },
  "message": "Added 1 gs1(s) as available to redeem",
  "execution_id": "9fc7f4db-c5ca-41c7-8a65-65be4bcd8e76",
  "execution_time_in_ms": 2405,
  "execution_start_time": 1587495466023
}
        
        

Step #2.2 : Rollback a Coupon

curl -X DELETE '{{API_SERVER}}/retailer/rollback/<GS1 to Rollback> \
-H 'Content-Type: application/json' \
-H 'x-access-key: ACCESS_KEY' \
-H 'x-access-token: ACCESS_TOKEN' 
        

Authorize Accelerator to manage redeem / rollback

Retailer can authorize the Accelerators to call redeem / rollback API on their behalf. An accelerator is an entity that has a connection to the retailer POS and has the ability perform these API functions in or on behalf of the POS. They are responsible to change the point of sale software to redeem / rollback 8112 barcode. To do that, first get the list of accelerators connected to The Coupon Bureau®

All Accelerators

If you find the vendor who is managing your point of sale system software, you can allow them to implement redeem / rollback on your behalf. You can use the below API calls to assign / unassign accelerator.

Assign/Unassign Accelerators


Authorize Clearinghouse to manage settlement

Retailer can authorize one clearinghouse to do the final settlement with the coupon manufacturer. Once they authorize a clearinghouse, the clearinghouse will be able to see the real time redemption and do the final settlement. To authorize a clearinghouse, retailer can call get_clearinghouses API to get the list of clearinghouses connected to The Coupon Bureau®

All clearinghouses

Retailer can assign / unassign clearinghouse using the below API calls

Assign / Unassign clearinghouse


Clearinghouse Getting Started Guide

Retailer clearinghouse will be able to view the redemption report of authorized retailers. Retailers connected to The Coupon Bureau® will authorize a clearinghouse to do the final settlement with the manufacturer. Once the clearinghouse is authorized, they will be able to view the redemption data in realtime.

Step #1 : Get Access Token

curl -X POST '{{API_SERVER}}/access_token' \
-H 'Content-Type: application/json' \
--data '{ 
    "access_key": "ACCESS_KEY", 
    "secret_key": "SECRET_KEY" 
}'

The Access Token will be valid for 24 hours. You should cache it and use the same access token for next 59 mins to call any other manufacturer APIs.

Get Funder

This API will send back manufacturer settlement billing details for the Funder ID sent by the retailer clearinghouse.

curl -X GET '{{API_SERVER}}/clearinghouse/funder/FUNDER_ID' 
-H 'Content-Type: application/json' 
-H 'x-access-key: ACCESS_KEY' 
-H 'x-access-token: ACCESS_TOKEN'
          

Get Updated Funders List

This API can be used to get a list of all manufacturer settlement billing details that have changed within a specific date range.

curl -X GET '{{API_SERVER}}/clearinghouse/funders/updated_list/<FROM_DATE (YYYY-MM-DD)>/<TO_DATE (YYYY-MM-DD)>/<PAGE_NO (E.g. 0,1...)>' 
-H 'Content-Type: application/json' 
-H 'x-access-key: ACCESS_KEY' 
-H 'x-access-token: ACCESS_TOKEN'
        

Base GS1 Validation

The purpose of this API is to confirm that each base data string in a redemption file is valid and to return the offers details for any necessary audit.

curl -X GET '{{API_SERVER}}/clearinghouse/basegs1/<BASE_GS1>' \
-H 'Content-Type: application/json' \
-H 'x-access-key: ACCESS_KEY' \
-H 'x-access-token: ACCESS_TOKEN'
        

Accelerator Getting Started Guide

Accelerators will facilitate retailer connectivity to The Coupon Bureau Positive Offer File. The Coupon Bureau will authorize an Accelerator to execute coupon redemption/ rollback on behalf of multiple retailers. Retailers will use this accelerator connectivity as their connection to The Coupon Bureau Positive Offer File (POF).

When an AI (8112) serialized data string is scanned at the POS, the POS makes an API request to POF with that serialized data string. The POF will then return the serialized data string with a status of “success” or “Failure” – if “success,” it will also send additional purchase requirement data. The POS then uses the additional purchase requirement data from the API response to validate offer against basket data and apply the discount or send a rollback response if the discount cannot be applied.

Step #1 : Get Access Token

curl -X POST '{{API_SERVER}}/access_token' \
-H 'Content-Type: application/json' \
--data '{ 
    "access_key": "ACCESS_KEY", 
    "secret_key": "SECRET_KEY" 
}'

The Access Token will be valid for 24 hours. You should cache it and use the same access token for next 59 mins to call any other manufacturer APIs.

Step #2 : Get connected retailers.

Accelerator can perform operation (redeem / rollback) on behalf of an authorized retailer. Retailer connected to The Coupon Bureau® will authorize an Accelerator to do the work on their behalf.

curl -X GET '{{API_SERVER}}/accelerator/retailers' \
-H 'Content-Type: application/json' \
-H 'x-access-key: ACCESS_KEY' \
-H 'x-access-token: ACCESS_TOKEN'           

Step #3.1 : Redeem a Coupon

curl -X POST '{{API_SERVER}}/retailer/redeem' \
-H 'Content-Type: application/json' \
-H 'x-access-key: ACCESS_KEY' \
-H 'x-access-token: ACCESS_TOKEN' \
--data '{
    "gs1s":"<Comma seperated GS1s>",
    "selected_store":"<Retailer Store ID>",
    "retailer_email_domain":"<Retailer email domain>"
  }'                  

How to handle "redeem" API responses

"redeem" API responses will be returned in a JSON array, with each item corresponding to a GS1 from the "gs1s" request array.
Response fields (per data string item):

  status -> "success" or "failure"
  newly_redeemed -> List of data strings redeemed successfully
          {
            gs1: <data string redeemed>,
            master_offer_file: <Master offer file (base gs1) data string> Refer to master_offer_files mapping to get the purchase requirements
          }
  master_offer_files -> Master offer file purchase details


Example response for redeem

{
  "status": "success",
  "total_gs1s_processed": 3,
  "already_redeemed": [
      "811201777777754545412323432"
  ],
  "not_yet_live": [
      "8112013333333676767223234543"
  ],
  "newly_redeemed": [
      {
          "gs1": "811201777777754545412323433",
          "master_offer_file": "8112017777777545454"
      }
  ],
  "master_offer_files": {
      "8112017777777545454": {
          "primary_purchase_gtins": [
              "678987654323",
              " 876789876543"
          ],
          "second_purchase_gtins": [],
          "third_purchase_gtins": [],
          "primary_purchase_save_value": 100,
          "primary_purchase_requirements": 1,
          "primary_purchase_req_code": 0
      }
  },
  "message": "Added 1 gs1(s) as available to redeem",
  "execution_id": "9fc7f4db-c5ca-41c7-8a65-65be4bcd8e76",
  "execution_time_in_ms": 2405,
  "execution_start_time": 1587495466023
}
        
        

Step #3.2 : Rollback a Coupon

curl -X DELETE '{{API_SERVER}}/accelerator/rollback/<GS1>' \
-H 'Content-Type: application/json' \
-H 'x-access-key: ACCESS_KEY' \
-H 'x-access-token: ACCESS_TOKEN'              

3rd Party Data Access

There are scenarios wherein you will need to fetch data from TheCouponBureau® to integrate and enhance your own SAAS platform. Imagine, your client #1 is managing their coupons inside your SAAS platform. Now, your client #1 is also subscribed to TCB as a Manufacturer Agent. You are a SAAS provider and subscribed to TCB as Authorized partner. Your client #1 wants to manage coupons, view redemption report in your platform and the data is available in TCB database. To access data from TCB platform for your client #1,

Step #1 : Ask your client #1 to login to TCB from your portal

Construct TCB Access URL and redirect your client #1 to that URL. Your client #1 will login to TCB, on successful login, TCB will generate a temporary token and redirect to the URL you will specify while constructing the TCB Access URL. To construct the TCB Access URL, you need the followings

• access_key You will get it from developer access page
• secret_key: You will get it from developer access page
• redirectURL: the URL which TCB will use to redirect on successful login. This URL will receive temp_token as GET parameter.
• timestamp: Epoch timestamp. Click here to get the current epoch timestamp

md5(access_key + redirectURL + timestamp + secret_key)
                    

{{API_SERVER}}/oauth_access?
  access_key=ACCESS_KEY&
  redirectURL=REDIRECT_URL&
  timestamp=TIMESTAMP&
  signature=CALCULATED_SIGNATURE
                    

redirectURL?temp_token=TEMPORARY_TOKEN                        
                    

md5(temp_token + secret_key)
                    

{{ API_SERVER }}/oauth_token?temp_token=TEMPORARY_TOKEN&signature=CALCULATED_SIGNATURE
                    

Near-realtime Webhook

If you need to receive realtime updates about the coupons (serialized data strings), you can register your webhook url and TCB will keep sending events in realtime. TheCouponBureau® backend will generate events on the below actions. If you are authorized to receive the event, TCB will send push message to your configured webhook so that you can process it as per your need.

Step #1 : Save Webhook

Go to your homepage, click on Enterprise Setting, enter the webhook url and click save button. Your webhook url should be active. TCB backend will check the webhook by sending a HTTP POST request with JSON body

{
  "TCBVERIFIER": "..."
}
                    

Step #2 : Verify Domain Ownership

TCB will verify the ownership of the webhook domain just to make sure you own the domain. There are three verification methods

• using DNS Add a TXT record to verify that you own the domain
• using hosted file: host a file in your server to verify the ownership of the domain
• using hosted endpoint: create an endpoint in your server to prove the domain ownership

Step #3 : Process Incomming Request

A TCB push request looks like this example below. Note that the message.data field is base64-encoded.

{
  "message": {
    "data": "SGVsbG8gQ2xvdWQgUHViL1N1YiEgSGV...........",
    "messageId": "136969346945"
  },
  ...
}
                    

204 No Content
                    

{
  gs1: 'GS1 data string (coupon)', 
  action: 'deposited',
  primary_signature: '...',
  secondary_signature: '...'
}
                    

{
  gs1: 'GS1 data string (coupon)', 
  action: 'deposited',
  primary_signature: '...',
  secondary_signature: '...',
  redeemed_at_store: {
    name: '...', // store name
    city: '...',
    state: '...',
    country: '...',
    retailer_email_domain: '...' // Retailer who redeemed this coupon
  }
}
                    

curl -X GET 'https://try.thecouponbureau.org/retailer/detail/<retailer_email_domain>' 
-H 'Content-Type: application/json' 
-H 'x-access-key: ACCESS_KEY' 
-H 'x-access-token: ACCESS_TOKEN'
                    

Primary / Secondary signature will help you validate that the message is originated at TheCouponBureau® server and it is intended for you. As soon as your callback is approved (Enterprise Setting page), you will see two secret keys (primary and secondary) associated with your callback.

TheCouponBureau® backend will sign the message before pushing to your webhook using both primary and secondary keys and send those to your webhook as primary_signature / secondary_signature. Webhook implementation should recalculate the signatures and proceed execution if any one of the signatures matches.

• primary_signature will be calculated using Primary Callback Secret
• secondary_signature will be calculated using Secondary Callback Secret

primary_signature = md5 ( concat(gs1 + action + primary callback secret) )

secondary_signature = md5 ( concat(gs1 + action + secondary callback secret) )
                    

Two secret keys concept will enable you rotate the key in case you want to change your keys. Here if the process you can use to safely rotate two keys.

• Regenerate primary secret
• Key change will take some time to reflect across TCB backend cluster
• In the meantime, your backend will keep matching secondary_signature value
• Once the key change is reflected across TCB cluster, which will take atleast 300 seconds, your primary_signature will start matching
• You can now safely regenerate secondary secret
• Your backend will keep matching primary_signature for sometime till secondary key will get stabilised in TCB cluster

Your webhook should calculate both signatures and continue if any one of the signatures matches. This will enable your to make sure that the messages are generated from TCB backend and not from other sources. As your endpoint is publicly available, its highly recommended to implement and validate signatures before processing the messages.

Action will be any of the followings

• deposited: new data string is deposited by provider
• deleted: data string is deleted by provider
• redeemed: deposited data string is redeemed by retailer / accelerator
• rollback: redeemed data string is rollbacked by retailer / accelerator

NOTE: Duplicate Message

TCB backend follows AT LEAST ONCE delivery mechanism. This means your webhook might receive duplicate messages. Its recommended to make your webhook idempotent using the messageId key which will be passed along with every message.

Reliable Delivery

TCB backend will ensure 100% reliable message delivery and in case your webhook is down, you will not loose any message. As soon as your webhook comes back, TCB will send all the messages you had missed during downtime. If your endpoint fails to respond with in few seconds, TCB backend will assume that the message delivery has failed and will retry. This might generate duplicate messages at your end. Your endpoint should reject the messages you had processed so far. Every message will have a unique messageId which you can use to detect duplicate messages.

Retry window

TCB backend will keep the message in Queue for 7 days and will keep retrying periodically. In case your endpoint fails to receive message within 7 days, TCB will remove the message from the message queue permanently.

Embeddable Widgets

Extend your own SaaS platform by embedding TheCouponBureau® Master Offer File management widgets as iframe. There are three widgets available to embed.

• Create Master Offer File Widget
• Manage Your Master Files Widget
• Edit Your Master File Widget

Step #1 : Get Access Token

curl -X POST '{{API_SERVER}}/access_token' \
-H 'Content-Type: application/json' \
--data '{ 
    "access_key": "ACCESS_KEY", 
    "secret_key": "SECRET_KEY" 
}'
                    

Step #2 : Create Widget Link

You have to pass following query parameters to load the secure widgets.

• x-access-key
• x-access-token

NOTE: Access token acquired via 3rd party data access protocol will also work here. Widget link will be active till the access token expires.

Create Master Offer File Widget Link

{{API_SERVER}}/enterprise/product/Manufacturer/create_mof/noheader?x-access-key=ACCESS_KEY&x-access-token=ACCESS_TOKEN
                    

Manage Master Offer Files Widget Link

{{API_SERVER}}/enterprise/product/Manufacturer/my_mofs/noheader?x-access-key=ACCESS_KEY&x-access-token=ACCESS_TOKEN
                    

Edit Master Offer File Widget Link

{{API_SERVER}}/enterprise/product/Manufacturer/my_mofs/noheader?x-access-key=ACCESS_KEY&x-access-token=ACCESS_TOKEN&base_gs1=BASE_GS1