# Getting Started with Wildfire API's and JSON feeds

Wildfire API & JSON feeds allow partners to access Wildfire's data-rich affiliate network coupons and cashback opportunities, for partners building their own offer walls, extensions, marketing efforts, and more.

Ensure you read through the essential information:

1. Regarding our API & JSON structures:
   1. [Getting to know the Wildfire JSON Data Feeds](https://kb.wildfire-corp.com/article/bbiw-getting-to-know-the-wildfire-json-data-feeds)
   2. [Syncing Commission Data via API and Callbacks](https://kb.wildfire-corp.com/article/kfgi-syncing-commission-data-via-api-and-callbacks)
   3. [Coupon Data JSON Structure](https://kb.wildfire-corp.com/coupon-data-json-structure)
   4. [Working with Wildfire Coupon Data](https://kb.wildfire-corp.com/article/aja2b-working-with-wildfire-coupon-data)

2. How to Handle Multiple Countries:
   1. [Country filtering and multiple applications](https://kb.wildfire-corp.com/country-filtering-and-multiple-applications)

3. How to build links and tracking codes for cashback:
   1. [Creating links](https://kb.wildfire-corp.com/article/joex-creating-links)
   2. [Tracking Code (TC) Parameter](https://kb.wildfire-corp.com/article/pl3-tracking-code-tc-parameter)

Feel free to reference this checklist:

**Preparation & Setup Logic**

**If paying out users, install the Postman Collection**: Use the pre-built collection with the included pre-request script to automatically generate the required HMAC authentication headers for API testing.

**Ingest Sample Data**: If live traffic is not yet active, ingest the Public Commission Sample Data (where ApplicationID is 0) to validate your dashboard’s ability to parse and display status changes.

**Coupon Data Feed Logic**

Because the Coupon Data Feed provides raw data, the following logic must be implemented in the partner application:

- **Coupon Data Feed - Normalize Descriptions:** If the Code field is null, parse the Description field to extract coupon code patterns.
- **Coupon Data Feed - Manual Country Filtering:** The feed is not pre-filtered by region. Partners must filter coupons using the provided country codes to match the user's location.
- **Coupons Data Feed - Date Validity Management:**
  - Suppress expired promotions.
  - Handle "coming soon" promotions (future start dates).
  - Interpret "Year 3000" end dates as "No Expiration."
- **Coupons Data Feed - Language Handling:** Filter or translate coupons if the merchant passes codes in a language not supported by your UI (e.g., US merchants passing Spanish coupons).

**Merchant & Rate Logic Feed**

- **Identify rate types:** PERCENTAGE vs. FLAT. If a rate is FLAT, check the Currency field (e.g., USD, CAD, EUR).
- **Cache Refresh Rate:** Implement a scheduled task to refresh the Merchant Data Feed at least once every 24 hours. Optional: Refresh Coupon Data Feeds every 6 hours to capture short-lived offers.
- **Disclaimer Logic:** Your UI must display "Up to [X]%" and include disclaimers that rates are subject to change.

**Link Construction**

- **Device ID Generation:** Your system must call POST /device to generate a Device ID for each unique user context before constructing links.
- **If doing Cashback - User Attribution (tc parameter):** To attribute a sale to a specific user in your system, you must append &tc=[Your_User_UUID] to the tracking link. Wildfire will return this value in the commission report.
- **Deep Linking:** When linking to a specific product page, you must URL-encode the target URL and append it as the last parameter (&url=...) to prevent truncation by browsers.
- **Multi-Country Override:** If your application serves users in multiple countries but uses a single App ID, you must detect the user's location and append &pc=[CountryCode] (e.g., &pc=CA) to tracking links to force the correct merchant program.

**Compliance Logic**

- **Accommodate Stand-down Logic:** Regularly ingest the stand-down-policy JSON feed. This contains a list of domains and URL parameters (e.g., afsrc=1) that indicate a user is already affiliated with another publisher.
- **Accommodate Session Suppression:** If a user visits a URL matching the Stand-Down list, your application (extension) must suppress all activation prompts for the duration of the user's session (typically 1 hour).

**Commission Reporting & Payout Logic**

- **Signature Verification:** When receiving a Callback (webhook), calculate the SHA-256 HMAC of the request body using your Callback Key, then compare it to the X-Wf-Signature header to verify authenticity.
- **De-Duplication:** Callbacks fire on every status change. Your system must upsert (update or insert) records by CommissionID to avoid creating duplicate entries for the same transaction.
- **Reconciliation (Failsafe):** Callbacks are "fire and forget" (no retries). You must implement a nightly batch job that uses the Commission API to fetch records modified in the last 24 hours and ensure any missed webhooks are captured.
- **Status Management:** Do not release funds to users while the status is PENDING or CONFIRMED. Wait for the status to change to **PAID** (or **READY** if you assume the risk) before crediting user wallets.
- **Split Handling (v4 API):** They need to handle the split payout and Offer presentation. You will see two SplitPart values: APPLICATION (your share) and DEVICE (the user's share).

Updated 16 Jun 2026