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
To get master offer file(s) created by you
Delete master offer file
My master offer files
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.
Master offer file detail
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
To get master offer file(s) created by you
Assign / Unassign provider for master offer file
Delete master offer file
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............VLI
PROVIDER_PREFIXCONSUMER_IDENTIFIER
VLI = Length(PROVIDER_PREFIX) + LENGTH(CONSUMER_IDENTIFIER) - 6
Use Serialization Prefix API to get your PROVIDER_PREFIX
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.
Get Connected Retailers:
Retailer will allow the accelerator to perform operation on their behalf. In this step, accelerator will pull the list of authorized retailers so that they can use the appropriate retailer_client_id while making the API calls
Redeem:
This is the primary API endpoint for TCB Positive Offer File functionality. The accelerator (on behalf of a retailer) sends scanned serialized data string(s) to POF, and POF responds with one or more serialized data strings. with "success" or "failure" for each.
"success" means the serialized data string is available for redemption
"failure" means the serialized 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 complete serialized data string as "redeemed", meaning the same complete serialized data string cannot be used more than once.
On "success", ", the serialized 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:
Depending on the point of sale implementation, it may be necessary to "rollback" relevant data string redemptions. For example, if "redeem" is called before the point of sale confirms payment, and payment is rejected, any complete data strings previously "redeemed" during the checkout process must be rolled back.
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)Then you construct the TCB Access URL by sending access_key, redirectURL and signature as GET parameters.
{{API_SERVER}}/oauth_access? access_key=ACCESS_KEY& redirectURL=REDIRECT_URL& timestamp=TIMESTAMP& signature=CALCULATED_SIGNATURE
TCB will then open a login window for your client #1 to login. It will also mention that, once you login, your data will be accessed by the SAAS provider.

On successful login, TCB will send a temp_token to the redirectURL.
redirectURL?temp_token=TEMPORARY_TOKENuse the temp_token to acquire the access_token which will be valid for 24 hours. To get the access_token, construct TCB Access Token URL by passing the temp_token and signature. You can calculate signature by using the following formula.
md5(temp_token + secret_key)
Send a GET request to TCB Access Token URL to acquire access_token for your client #1
{{ API_SERVER }}/oauth_token?temp_token=TEMPORARY_TOKEN&signature=CALCULATED_SIGNATURE
You should cache the access_token against your client #1 in your system to continue using it to make various API calls on your client's behalf. Client Access Token will be valid for 180 days. You should ask your client to relogin once the access_token had expired.
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": "..." }Your webook endpoint should return HTTP Status Code: 200. If it fails to do that, you will get an error message while saving the webhook.
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" }, ... }Your webhook needs to handle incoming messages and return an HTTP status code to indicate success or failure. A success response is equivalent to acknowledging a message. The status codes interpreted as message acknowledgements by the TCB backend system are: 200, 201, 202, 204. A success response might look like this:
204 No Content
If your webhook does not return a success code, TCB retries delivery for 7 days before it will expire. Once you decode the message.data, you will get the below message
{ gs1: 'GS1 data string (coupon)', action: 'deposited', primary_signature: '...', secondary_signature: '...' }
In case of redemption event, there will be an additional information passed (redeemed_at_store) to the webhook endpoint
{ 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 } }
Actual retailer name can be fetched by using retailer_email_domain value
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
E.g. WIDGET_URL?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