# 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

## Response Schema

A successful response returns a Merchants array along with pagination metadata.

```json
{
  "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 |
| 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 |
| 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.

```json
{
  "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"
  }
}
```

### Coupons Object

The Coupons array replaces the need to consume the coupon feed separately. By returning coupons available for the requested merchant.

```json
{
  "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
}
```

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

#### Filter by Category  
q=PrimaryMerchantCategoryID:17

Multiple categories:

q=PrimaryMerchantCategoryID:17 OR PrimaryMerchantCategoryID:1

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