Best Practices
How Wildfire Partners Receive Commission Payments from Wildfire and Pay a Share to Their Users
Some partners pass along all earned commissions to their end users, some keep a share of that revenue for themselves, and still others have Wildfire implementations where the partner keeps all commissions.
When merchants notify Wildfire about commissions, Wildfire notifies the appropriate Wildfire partner via a callback. The callback looks like this:
The partner should then store commission data from these callbacks into their own database. Every time a commission changes (like a change in status or a change in amount) another callback is sent for that same commission ID. Most Wildfire partners choose to pass in a tracking code that contains a user ID for all commissions to make it straightforward to pay their end users when that commission is eligible to be paid. Read more about Tracking Codes: Tracking Code (TC) Parameter
Please note: Wildfire is unaware of commissions until they are reported by the merchant, which is why you will notice there is both a CreatedDate and an EventDate reported about the commissions- EventDate is the timestamp of when the transaction that earned the commission actually happened (i.e., your end user bought something at Macy's at 2021-10-21T16:37:00Z), and CreatedDate is when Wildfire learned about the commission and created it in our database (i.e., Macy's reported to Wildfire at 2021-10-22T03:37:48.269501Z that your end user bought something at Macy's.)
As a failsafe, in case the callbacks missed any commission updates, partners should continuously (once daily is a common cadence) ingest commission data using the Commission API and ingest anything that may have been missed.
Commissions go through a normal lifecycle with updates communicated via the callbacks and APIs, as shown below:
As shown above in the Commission Payment Timeline, when Wildfire is paid for a commission, the commission status is updated to "READY."
At the beginning of each month, Wildfire retains its portion of the commission revenue and sends the remainder to the partner for all commissions that have been updated to the status, "READY" since the last payment to the partner. Wildfire partners receive their commission revenue in one lump sum, most commonly by wire transfer directly to the partner's bank account.
Once payment to the partner is complete, Wildfire updates those commissions to the status, "PAID."
From the commission data, the partner now has all the information needed to pay their users their share of the commissions earned. The partner should then pay end users their share of all the commissions (a bunch of commissions will now have a status of PAID) by whatever payout method the partner prefers.
Partners should store an internal status (e.g.; USERPAID) for each commission ID that has been paid by the partner to the end user.
Additional considerations and recommendations
When commission data is received, Wildfire recommends that partners store any device IDs associated with that tracking code in another table. This allows partners to reconcile any commissions that are not able to be mapped by tracking code for any reason. At the beginning of the month, after payment is sent to the partner, a Payment Detail Report is made available in the Partner Admin Tools as a csv file to download. This report details all the commissions paid in that month's lump sum payment to the partner and includes Commission ID, Sale Amount, Commission Amount, Sale Amount Currency, Commission Currency, Tracking Code, Event Date, and Merchant.)
When a commission is READY, it will never be clawed back and is promised to the partner in the next payment from Wildfire. For this reason, some Wildfire partners choose to pay their end users when the status for a commission is READY, rather than wait until they actually have the funds in hand from Wildfire and the commission is PAID.
