Offer Wall Merchant Search API

17 min

offer wall merchant search api overview the offer wall merchant search api is a new single queryable endpoint that gives you real time access to wildfire's full merchant catalog — including commission rates, coupon data, merchant metadata, logos, domains, and category information — all in one response for existing clients, building an offer wall required ingesting & stitching together multiple separate json feeds managing your own caching layer, and keying records across feeds by merchant id this api aims to eliminates that entirely what you needed before what you get now merchant feed — logos, metadata, scores ✅ included in every merchant response merchant rate feed — commission rates ✅ included as maxrate, maxratekind, detailedrates coupon feed — promo codes and offers ✅ included as coupons\[] array active domain feed — merchant domains ✅ included as merchantdomains\[] category feed — category taxonomy ✅ included as categorybreadcrumbs featured merchant feed — curated top brands ✅ included as isfeaturedmerchant note the stand down policy feed is specific to browser extension compliance and is not part of this api if you are building a browser extension, you still need to consume that feed separately getting started endpoint https //api wfi re/v1/offerwall merchant/{app id}/search?q={ query } replace {app id} with your wildfire client application id that corresponds with your shopping portal/offer wall insert any parameters to customize your query authentication no authentication headers are required at this time your app id in the url path scopes results to your application parameters parameter required default description \q\ yes — your search query \sort\ no by relevance sort order (see sorting below) \pagenumber\ no 1 page number for pagination \pagesize\ no 100 results per page (max 100) example queries search by merchant category https //dev api wfi re/v1/offerwall merchant/{app id}/search? \q\ =(primarymerchantcategoryid 33 or parentcategoryid 33) and (maxratekind "percentage" or (maxratekind "flat" and maxratecurrency "usd"))& \sort\ =merchantscore desc& \pagesize\ =30& \pagenumber\ =1 search by merchant https //dev api wfi re/v1/offerwall merchant/{app id}/search? \q\ =merchantid 5475228 very more common queries here https //app archbee com/docs/taiv d34rovd9o2bve8q3/ev9fqto5kq8p7g zq1lbr#otwem response schema a successful response returns a merchants array along with pagination metadata { "merchants" \[ ], "pagecount" 1, "pagesize" 100, "totalcount" 1 } merchant object each merchant in the array contains the following fields field type description merchantid integer unique wildfire merchant identifier merchantname string merchant display name merchantdomains string\[] all active domains for this merchant merchantscore integer wildfire quality score (higher = better) isfeaturedmerchant boolean whether this is a wildfire curated featured merchant primarymerchantcategoryid integer primary category id merchantcategoryids integer\[] all category ids this merchant belongs to categorybreadcrumbs object human readable category paths keyed by category id maxrate float highest available commission rate for this merchant maxratekind string percentage or flat maxratecurrency string iso currency code for flat rates (e g usd); empty for percentage rates detailedrates object\[] full breakdown of all commission tiers (see below) boosted boolean whether the merchant currently has a boosted offer active originalrate float pre boost rate, when boosted is true coupons object\[] all available coupon and promotional offers (see below) brandcolor string background to use with logotransparentimage logoimageexists boolean whether a logo is available logoimageurl string square logo logorectimageurl string rectangular logo logotransparentimageurl string logo with transparent background logolifestyleimageurl string higher resolution lifestyle/featured image than the featuredimageurl featuredimageurl string banner/featured image createddate string (iso 8601) date merchant was added to the platform modifieddate string (iso 8601) date merchant record was last updated detailedrates object detailedrates contains one entry per commission tier and replaces the need to reference the merchant rate feed { "id" 383397, "name" "womens/mens clothing, and garden supplies purchases", "kind" "percentage", "amount" "2 925", "boostedoffer" { "originalamount" "0", "multiplier" "0", "percentage" "0", "enddate" "0001 01 01t00 00 00z" } } field description id unique rate ledger id name human readable description of what this rate applies to kind percentage or flat amount rate value as a string — parse as float boostedoffer active boost details if applicable; all zeros when no boost is active note amount is returned as a string, not a number parse it to a float before performing any calculations a value of "0" means no commission is paid on that tier coupons object the coupons array replaces the need to consume the coupon feed separately by returning coupons available for the requested merchant { "code" "newusoff5", "description" "new users get $5 off when you spend $20", "discountamount" 5, "discounttype" "flat", "enddate" "2026 06 30t16 16 00z", "startdate" "2026 04 03t16 17 00z", "isfreeshipping" false, "issitewide" false, "minimumspend" 20, "minimumquantity" 0, "offercurrencyid" 840, "parseconfidence" 0 42, "successrate" 0, "winrate" 0, "couponsource" "description", "networkmerchantcouponid" 5171334 } field description code coupon code to apply at checkout — may be empty for promotions with no code description human readable offer description discountamount discount value — interpret in context of discounttype discounttype percentage, flat, or empty string isfreeshipping whether this offer includes free shipping issitewide whether this offer applies to the entire store minimumspend minimum purchase amount required — 0 means no minimum minimumquantity minimum item quantity required — 0 means no minimum offercurrencyid iso 4217 numeric currency code (840 = usd, 124 = cad); 0 = not currency specific startdate / enddate validity window parseconfidence wildfire confidence score for automated parsing (0–1); lower values warrant more caution before surfacing in ui successrate empirical redemption success rate where available winrate commission win rate where available couponsource how the coupon was sourced (e g description) common query examples examples find a specific merchant by name q=merchantname\ walmart for multi word names, wrap in quotes q=merchantname "home depot" name matching is not case sensitive and matches on exact whole words partial word matches are not supported — merchantname "diabetes sto" will not return "diabetes store " find a merchant by id q=merchantid 5475228 find featured merchants q=isfeaturedmerchant\ true find merchants with active boosts q=boosted\ true filter by commission rate always pair maxrate with maxratekind to avoid mixing percentage and flat results q=maxrate >5 and maxratekind\ percentage for a flat rate in a specific currency q=maxrate >5 and maxratekind\ flat and maxratecurrency\ usd for a rate range q=maxrate \[5 to 10] and maxratekind\ percentage filter by category q=primarymerchantcategoryid 17 multiple categories q=primarymerchantcategoryid 17 or primarymerchantcategoryid 1 to find category ids, reference the wildfire category feed documentation or use a wildcard query (q= ) and inspect the categorybreadcrumbs in the response find merchants with logos useful for filtering to merchants you can display in a ui with imagery q=logoimageexists\ true find merchants with sitewide coupons q=coupons issitewide\ true other coupon filters q=coupons isfreeshipping\ true q=coupons discountamount >=20 q=coupons code\ save filter by detailed rate tier q=detailedrates kind\ percentage and detailedrates amount >=5 combine multiple conditions q=isfeaturedmerchant\ true and maxrate >5 and maxratekind\ percentage and merchantscore >80 filter by date added q=createddate \[2025 01 01 to 2025 12 31] merchants added after a specific date q=createddate \[2025 06 01 to ] sorting append \&sort= to control result order sort expression result maxrate desc highest commission first merchantscore desc best quality score first createddate desc newest merchants first merchantname asc alphabetical isfeaturedmerchant desc, maxrate desc featured first, then by rate example q=primarymerchantcategoryid 33\&sort=merchantscore desc wildcards q=merchantname\ mart ✅ matches mart, marty's, martini q=merchantname\ wa?mart ✅ matches walmart, wagmart q=merchantname mart ❌ leading wildcards are not supported edge cases and gotchas certain edge cases to watch out for 1 no match fallback returns all results if a query has no exact matches — for example, a name containing a special character like an apostrophe without proper quoting — the api may return all results rather than an empty set always check the totalcount field in the response a value of exactly 10000 is a strong signal that the query fell back to returning everything // incorrect — apostrophe causes a parse failure, may return all results q=merchantname\ lowe's // correct q=merchantname "lowe's" 2 case sensitivity rules different parts of the query have different casing requirements what rule example boolean operators uppercase only and, or, not range keyword uppercase only \[2025 01 01 to 2025 12 31] field names exact casing merchantname, maxrate, isfeaturedmerchant maxratekind values uppercase percentage, flat detailedrates kind values uppercase percentage, flat coupons discounttype values lowercase flat, percentage 3 date format dates must use yyyy mm dd format time components are not supported ✅ createddate \[2025 01 01 to 2025 12 31] ✅ coupons startdate >"2025 11 01" (note quotes required with > syntax) ✅ coupons startdate \[2025 11 01 to 2025 11 05] ❌ createddate \[2025 01 15t10 30 00z to ] ❌ createddate >2025 11 01 (missing quotes with > syntax) 4 numeric values require leading zeros decimal values less than 1 must include the leading zero ✅ maxrate >0 5 ❌ maxrate > 5 5 url encoding special characters in query strings must be url encoded most http libraries handle this automatically, but if you're constructing urls manually character encoded %3a > %3e \[ %5b ] %5d space + or %20 6 nested field conditions apply to the same item when filtering on multiple coupons or detailedrates fields, both conditions must be satisfied by the same nested item — not one condition per item this query finds merchants where a single coupon has both a flat discount and a discount amount greater than 20 q=coupons discountamount >20 and coupons discounttype\ flat it does not match a merchant that has one coupon with amount > 20 and a different coupon of type flat 7 nested field responses may include non matching items when a query matches on a nested field (e g coupons ), the full coupons array for that merchant is returned — not just the matching coupon(s) the response may contain coupons that do not satisfy your filter criteria always validate nested items client side before surfacing them in your ui do not assume the api has pre filtered the nested array 8 field existence check to find merchants where a field has any value at all, use field q=coupons code // merchants that have at least one coupon record q=detailedrates amount // merchants with commission rate data to find merchants where a field exists and is not empty q=coupons code and coupons code "" best practices always pair maxrate with maxratekind filtering on rate alone mixes percentage and flat values , making comparisons meaningless if building a usd only experience, also add maxratecurrency\ usd when filtering on flat rates use merchantscore desc for quality ranking when building an offer wall or category page, sorting by merchantscore desc surfaces the highest quality, most reliable merchants first filter to logoimageexists\ true for display experiences merchants without logos will result in broken ui when building any visual offer wall, add this filter to your base query validate nested coupon fields before display due to the response behavior described in edge case #7, always check that each coupon in the coupons array actually satisfies your criteria before rendering it in particular, check discounttype, discountamount, enddate, and offercurrencyid on the client check parseconfidence before surfacing coupon codes coupons with low parseconfidence (below 0 5) were parsed automatically and may have incomplete or misleading descriptions consider applying a minimum confidence threshold for display in consumer facing experiences use totalcount as a sanity check if your query returns exactly 10000 results, it likely fell back to returning all merchants due to a malformed query review your syntax before using the results paginate thoughtfully pagesize is capped at 100 for large result sets, paginate using pagenumber and use totalcount and pagecount to determine how many pages to request scope by offercurrencyid for multi region deployments coupon amounts are not always in usd if your platform serves a specific market, filter or label coupons by offercurrencyid to avoid displaying incorrect discount amounts to users common values 840 = usd, 124 = cad syntax quick reference // exact match merchantname\ walmart // multi word value merchantname "home depot" // numeric comparison maxrate >5 maxrate >=5 maxrate <10 maxrate \[5 to 10] // inclusive range maxrate {5 to 10} // exclusive range // boolean operators (must be uppercase) condition1 and condition2 condition1 or condition2 not condition1 // grouping (condition1 or condition2) and condition3 // wildcards (trailing only) merchantname\ mart // multi character merchantname\ wa?mart // single character // field existence fieldname // nested fields coupons issitewide\ true detailedrates kind\ percentage review a full sample response explore a sample respon se for aliexpress { "merchants" \[ { "appid" your app id, "merchantid" 5475228, "merchantname" "aliexpress", "merchantdomains" \[ "aliexpress us", "aliexpress com" ], "merchantscore" 1, "isfeaturedmerchant" false, "primarymerchantcategoryid" 33, "merchantcategoryids" \[ 22, 45, 70, 29, 17, 1, 5, 3, 28 ], "categorybreadcrumbs" { "1" \[ { "id" 1, "name" "clothing & apparel" } ], "10" \[ { "id" 10, "name" "erotic" } ], "102" \[ { "id" 29, "name" "computers & accessories" }, { "id" 102, "name" "tablets" } ], ], "181" \[ { "id" 22, "name" "health & beauty" }, { "id" 181, "name" "personal care" } ], "185" \[ { "id" 20, "name" "hardware" }, { "id" 185, "name" "tools" } ] }, "maxrate" 2 93, "maxratekind" "percentage", "maxratecurrency" "", "maxrateledgerid" 11489217, "boosted" false, "originalrate" 0, "featuredimageurl" "https //storage googleapis com/wl image/bd37fbcce3987c9db71a9358934dbb7fe4ecd0ee", "createddate" "2018 03 13t17 34 48 990289z", "modifieddate" "2026 05 21t00 07 07 845337z", "maxofferscore" 0, "detailedrates" \[ { "id" 364858, "name" "2025 polarized prescription sunglasses purchase or gift cards", "kind" "percentage", "amount" "0", "boostedoffer" { "originalamount" "0", "multiplier" "0", "percentage" "0", "enddate" "0001 01 01t00 00 00z" } }, { "id" 383074, "name" "all other online purchases", "kind" "percentage", "amount" "2 4375", "boostedoffer" { "originalamount" "0", "multiplier" "0", "percentage" "0", "enddate" "0001 01 01t00 00 00z" } }, { "id" 383397, "name" "womens/mens clothing, and garden supplies purchases", "kind" "percentage", "amount" "2 925", "boostedoffer" { "originalamount" "0", "multiplier" "0", "percentage" "0", "enddate" "0001 01 01t00 00 00z" } }, { "id" 383398, "name" "home/garden, hair/wigs, and appliance purchases", "kind" "percentage", "amount" "1 4625", "boostedoffer" { "originalamount" "0", "multiplier" "0", "percentage" "0", "enddate" "0001 01 01t00 00 00z" } } ], "coupons" \[ { "category" "", "code" "", "couponscore" 0, "couponsource" "description", "createddate" "2026 01 07t03 43 11 829629z", "description" "enjoy free shipping on all orders", "discountamount" 0, "discounttype" "", "enddate" "2030 10 17t00 00 00z", "isfreeshipping" true, "minimumquantity" 0, "minimumspend" 0, "modifieddate" "2026 01 07t03 43 11 829629z", "networkmerchantcouponid" 4985642, "offercurrencyid" 0, "offerscore" 0, "parseconfidence" 0 33, "shippinginfo" "within 2 8 days delivery for ship from us", "issitewide" true, "startdate" "2024 10 17t13 34 00z", "successrate" 0, "winrate" 0 }, { "category" "", "code" "", "couponscore" 0, "couponsource" "description", "createddate" "2026 01 07t03 43 19 059976z", "description" "top selling products up to 70% off plus free shipping plus fast delivery!", "discountamount" 70, "discounttype" "percentage", "enddate" "2029 03 02t05 00 00z", "isfreeshipping" true, "minimumquantity" 0, "minimumspend" 0, "modifieddate" "2026 01 07t03 43 19 059976z", "networkmerchantcouponid" 4985640, "offercurrencyid" 0, "offerscore" 0, "parseconfidence" 0 42, "shippinginfo" "fast delivery", "issitewide" true, "startdate" "2022 12 13t14 46 00z", "successrate" 0, "winrate" 0 }, { "category" "", "code" "newusoff3", "couponscore" 0, "couponsource" "description", "createddate" "2026 04 04t04 09 10 902466z", "description" "new users save $3 on $10 or more purchases", "discountamount" 3, "discounttype" "flat", "enddate" "2026 07 01t00 00 00z", "isfreeshipping" false, "minimumquantity" 0, "minimumspend" 10, "modifieddate" "2026 05 21t12 00 45 201024z", "networkmerchantcouponid" 5170091, "offercurrencyid" 840, "offerscore" 0, "parseconfidence" 0 42, "shippinginfo" "", "issitewide" false, "startdate" "2026 04 02t20 46 00z", "successrate" 0, "winrate" 0 }, { "category" "", "code" "mxss5", "couponscore" 0, "couponsource" "description", "createddate" "2026 05 16t03 34 50 313643z", "description" "up to 60% off", "discountamount" 60, "discounttype" "percentage", "enddate" "2026 05 22t15 59 00z", "isfreeshipping" false, "minimumquantity" 0, "minimumspend" 0, "modifieddate" "2026 05 16t03 34 50 313643z", "networkmerchantcouponid" 5284489, "offercurrencyid" 484, "offerscore" 0, "parseconfidence" 0 42, "shippinginfo" "", "issitewide" false, "startdate" "2026 05 17t16 00 00z", "successrate" 0, "winrate" 0 }, { "category" "", "code" "usaff5", "couponscore" 0, "couponsource" "description", "createddate" "2026 05 19t03 35 27 132462z", "description" "get $5 off $39! aliexpress' sunshine savings!", "discountamount" 5, "discounttype" "flat", "enddate" "2026 05 23t06 59 59z", "isfreeshipping" false, "minimumquantity" 0, "minimumspend" 39, "modifieddate" "2026 05 19t03 35 27 132462z", "networkmerchantcouponid" 5289316, "offercurrencyid" 840, "offerscore" 0, "parseconfidence" 0 5, "shippinginfo" "", "issitewide" true, "startdate" "2026 05 18t17 00 00z", "successrate" 0, "winrate" 0 }, ], "brandcolor" "#f52945", "textcolor" "", "logoimageexists" true, "logoimageurl" "https //storage googleapis com/wl image/b3d1408a9ad4cea736abdec2341f472e4740225b", "logorectimageurl" "https //storage googleapis com/wl image/e762fdd41fec20b76b1b59b0497adefa95173e1b", "logotransparentimageurl" "https //storage googleapis com/wl image/381086acd5cada08a7c0ab6db2aff59637137e8f", "logolifestyleimageurl" "https //storage googleapis com/wl image/d5dfb2942e436c479af37928ecfcfa432736c189" } ], "pagecount" 1, "pagesize" 100, "totalcount" 1 }