Coupon Data JSON Structure
8 min
introduction this document provides an overview of the json structure used to store coupon data for various merchant websites the json file contains information about coupon codes and css selectors used for auto applying coupons on specific merchant websites usage the json data is used to facilitate wildfire partners to deliver custom coupon codes to our extensions the extension will retrieve this data on a regular cadence in order to include your custom coupon codes and targets into your extension the codes section provides a list of available coupon codes, while the targets section provides css selectors for automating coupon application on websites that are not yet supported wildfire coupon data json feed available coupon data is located at the wildfire coupon json feed \<font color="#a855f7">https //www wildlink me/data/application id/coupon/version\</font> \<font color="#e9d5ff">\</font> expected fields id and merchant id id is the unique identifier for the coupon or promotion, and the merchant id is the associated merchant reference for the coupon/promo description contains details about the offer or promotion in some cases, the coupon code may also appear in this field some merchants do not provide structured or consistent descriptions, especially for coupon based offers for wildfire built products wildfire handles this on behalf of our partners for partner built products partners may need to normalize or clean up descriptions before displaying them in the ui code when provided, this field contains the coupon code entered at checkout to apply the discount note this field may sometimes be blank or show null for wildfire built products wildfire handles this on behalf of our partners for partner built products use the table below to determine how to interpret offer data scenario code field description field action required code only in description blank or null contains code extract code from description code in both fields contains code contains code use code field (preferred source) no code provided blank or null no code listed no code required; discount applies automatically (e g free shiping or sitewide sale) countries list of country codes where the merchant indicates the coupon can be used may include "international" may be null if not specified important notes the wildfire coupon feed is not filtered by country the json feed does not include a direct coupon to country relationship for wildfire built products wildfire manages country filtering for partner built products partners must control which coupons are displayed by count languages while network merchants sets the applicable countries for offer codes, they can still pass coupons available for that country in different languages for partner built products, partners must manage the display of applicable language i e a network merchant can pass us coupons & promos, but that does not mean eligible coupons are exclusively in english the eligible us coupons can be in french or spanish, etc exclusions some merchants explicitly list restrictions or exclusions (e g , brands, categories, regions) more commonly, eligibility details are included within the description field start date / end date defines when the coupon is valid may include future start dates (“coming soon” promotions) may include expired promotions some merchants use very long end dates (e g , year 3000) to indicate no expiration for wildfire built products wildfire manages validity filtering for partner built products partners must display only currently valid coupon feed regeneration cadence wildfire regenerates coupon data approximately every 6 hours plan caching and refresh logic accordingly to ensure accurate and timely offers json structure the json file is organized into an object where each key represents a merchant website's domain name the structure consists of two primary sections codes this section contains an array of coupon codes associated with the merchant website targets (optional) this section contains an array of css selectors that are used to automatically apply coupons on the merchant website the targets object is only needed if wildfire doesn’t already support this domain and auto coupon application is desired example below is an example of the json structure { "merchant domain 1 com" { "codes" \[ { "id" 1, "code" "save15" }, { "id" 2, "code" "freeship" }, { "id" 3, "code" "25off" } ], "targets" \[ { "input" "#coupon input", "price" " total price", "submit" " apply button", "remove" " remove button", "error" " error message", "before" " before coupon action" } ] }, "merchant domain 2 com" { "codes" \[ { "id" 4, "code" "discount4" }, { "id" 5, "code" "savings5" } ] }, // additional merchant domains } code section the codes section for each merchant domain contains an array of coupon objects each coupon object consists of id a unique identifier for the coupon code the actual coupon code targets section the targets section for each merchant domain contains an array of target objects each target object consists of css selectors used for specific actions input the selector for the coupon input field (i e a text input element) price the selector for the price or total amount on the webpage note this should be the total including the tax and shipping as some coupons will result in free shipping submit the selector for the submit button to apply the coupon remove the selector for the remove or cancel button to remove the coupon (if present, some merchants don’t include this functionality, in which case this value should remain empty) error the selector for any error messages that may appear (i e to describe a code as invalid for the contents of a specific shopping cart) before this is an optional selector for when the user must interact with an element to make the coupon input field visible note this json structure is adaptable and can be extended to accommodate additional merchant domains as needed it is essential to keep this json file updated with the latest coupon codes and target selectors to ensure proper functionality across various merchant websites summary wildfire's coupon data feed is raw data and may contain expected anomalies this raw data provides all wildfire partners with the maximum number of savings opportunities to present to their users for wildfire built products, these nuances are handled on behalf of our partners for partner built products, partners must manage the following extract specific coupon code patterns from descriptions refine dates shown to users; specifically for the no expiration date codes and promos handling countries; specifically, the translation of eligible coupons from non official languages to the official language, if desired