Syncing Commission Data via API and Callbacks - Wildfire Support Center

Syncing Commission Data via API and Callbacks

20 min

Once your users start generating sales, you'll want your system to sync the associated data so that you can show these sales to your users, send push notifications, etc.

There are two ways to get this commission data: pull them from our API or receive callbacks from our system. Our recommendation is to call our API, caching results between every 1-6 hours but no less than 24 hours. Callbacks are an additional option, however, we do not re-attempt failed callbacks.

Commission Data via the Wildfire API

To see the API docs for how to fetch commission data en masse see the API reference.

Features of commission API:

Fetch up to 2000 records at a time
Cursor-based requests to page through all results
Request commissions between a date_modified range to capture all changes

Notes:

Commission API should only be called up to 1 time per 5 seconds (more frequent requests will be rejected).
Whereas callbacks provide low-latency commission data, the batch API provides a guarantee of not missing any records (as callbacks are not retried).
Requests to the commission API can timeout for a number of reasons (network connectivity, unplanned maintenance windows, etc.). The HTTP response code and payload should be evaluated to ensure you received an expected response. If an unexpected response was received, consider retrying with an exponential backoff pattern.

Commission Data via Callbacks

Callbacks offer nearly realtime updates as commission records are created or changed in the Wildfire platform. However, Callbacks are not retried and no longer the recommended method for syncing commission records.

To set up your callback URL, in your partner admin tool, select the application you want to configure and then select the gear icon. Here you can enter a callback URL (please ensure it's an HTTPS endpoint) and a callback key.

The callback key can be any value. The purpose of the callback key is to ensure that the callback is valid (and that a rogue entity is not invoking your callback URL with false data).

Callback Body

The content of the body is different depending on what version of the APIs your application is configured to use.

By default, we subscribe an application when it is created to the most recent version of our APIs. Wildfire will not auto-update your application to a new version of the APIs but you may request to have your application(s) upgraded.

A V3 callback request will have a body similar to this:

{"ID":"96d0a222-c84c-4b6b-8722-8fb8447f9565","Type":"Commission","Action":"create","Payload":{"CommissionID":12345,"ApplicationID":0,"MerchantID":123456,"DeviceID":19283,"SaleAmount":{"Amount":"321","Currency":"USD"},"Amount":{"Amount":"3.211","Currency":"USD"},"Status":"PENDING","TrackingCode":"012345-6780a-bcdef0-12345","EventDate":"2019-09-12T01:22:33Z","CreatedDate":"2019-09-13T02:22:33.987654Z","ModifiedDate":"2019-09-13T02:22:33.987654Z","MerchantOrderID":"397254095","MerchantSKU":"465056245"},"CreatedDate":"2019-09-15T00:11:33.987654Z"}

A V4 callback request will have a body similar to this:

{"ID":"87f0a400-c84c-4b6b-8722-8fb8447f9565","Type":"Commission","Action":"create","Payload":{"CommissionID":775109,"ApplicationID":0,"MerchantID":98813,"DeviceID":12345,"SaleAmount":{"Amount":"384.65","Currency":"USD"},"Amounts":[{"Amount":"2.88475","Currency":"USD","SplitPart":"APPLICATION"},{"Amount":"5.7695","Currency":"USD","SplitPart":"DEVICE"}],"Status":"PAID","TrackingCode":"012345-6780a-bcdef0-74932","EventDate":"2022-10-27T23:08:45Z","LockingDate":"2022-10-27T23:08:45Z","CreatedDate":"2022-10-27T23:08:45.898588Z","ModifiedDate":"2022-10-27T23:13:45.898588Z","MerchantOrderID":"1234582725","MerchantSKU":"sku123nd"}}

V5 (Latest) Callback Response

{"ID":"3d9f2b6a-1e4c-4a8f-9c2d-7b6e5f4a3d21","Type":"Commission","Action":"create","Payload":{"CommissionID":775109,"ApplicationID":0,"MerchantID":98813,"DeviceID":12345,"DeviceXID":"3f9a8b2c-77d1-4e6a-9b0e-1a2b3c4d5e6f","SaleAmount":{"Amount":"384.65","Currency":"USD"},"Amounts":[{"Amount":"2.88475","Currency":"USD","SplitPart":"APPLICATION","BaseCommissionAmount":"2.50000","BoostedCommissionAmount":"0.38475"},{"Amount":"5.7695","Currency":"USD","SplitPart":"DEVICE","BaseCommissionAmount":"5.00000","BoostedCommissionAmount":"0.76950"}],"Status":"PAID","TrackingCode":"012345-6780a-bcdef0-74932","EventDate":"2022-10-27T23:08:45Z","LockingDate":"2022-10-27 23:08:45 +0000 UTC","CreatedDate":"2022-10-27T23:08:45.898588Z","ModifiedDate":"2022-10-27T23:13:45.898588Z","MerchantOrderID":"1234582725","MerchantSKU":"sku123nd","CouponCodes":"SAVE15OFF","ShoppingTripCode":"8f14e45f-ceea-467e-bd42-ee7b1b5f4e9c"},"CreatedDate":"2022-10-27T23:13:45.899123Z"}

New fields: DeviceXID, CouponCodes, ShoppingTripCode on the payload; BaseCommissionAmount and BoostedCommissionAmount added to every entry in Amounts.
**Status enum values:**PENDING, CONFIRMED, READY, PAID

_Note__: Both of the above examples include whitespace/indentation for readability, but when generating the HMAC check to verify this callback came from Wildfire, the callback body must be evaluated without modification (i.e. it should contain no indentation/whitespace/formatting).

Callback Key Values

ID: The callback ID. Note that this is different from the commission ID. Every callback request will have a unique callback ID, but it may have the same commission ID (i.e. in the case of an update). There is a button in Partner Admin that allows a user to resend a callback to your callback receiver URL. Every time that resend callback button is selected, a new callback will fire with a unique callback ID but the same commission ID.

Type: "Commission"

Action: "create", "update"

Commission Payload Key Values

CommissionID: Unique ID for this commission, when updates are sent this ID will be the same.

ApplicationID: The ID of the application with which the purchase was made.

DeviceID: The ID for the user’s device that made the purchase.

**MerchantID:**The ID for a merchant. This value can be used to match to a merchant in the JSON feed.

SaleAmount

Amount: Reported sale amount from merchant. Note: Some merchants don't report sale amount, this can be 0.
Currency: The original currency in which the purchase was made. This value is not converted to the application default currency.

Amounts: This is an array with up to two maps with data for the user’s earnings and the application’s earnings. If you pay your end user you will only see a map for the application SplitPart. If Wildfire pays your end users you will see two maps, one containing the user’s earnings and the other containing the application’s earnings.

**Amount:**The commission amount, this can be a negative number in the case of a canceled or returned order to offset the original commission (this will have a new ID).
Currency: Commissions are always converted to your application's default currency (e.g. if your default currency is CAD, this value will be sent via API and callback in CAD).
**SplitPart:**A split part is the amount of money allocated to one or two entities depending on the configuration of your application(s). In instances where you pay your end users directly, you will only ever see an Application split part. If Wildfire pays your end users on your behalf, this response will include both the Application SplitPart and the Device (end user) SplitPart. Note: SplitPart was added in v4 of commission records.
Application: Represents your portion of a commission.
Device: Represents the end user's portion of a commission. Only present in cases where Wildfire is paying your end user.

TrackingCode: This is the value referred to Tracking Code (TC) Parameter

EventDate: Timestamp for when the order was placed.

CreatedDate: Timestamp for when the commission was entered into our database.

ModifiedDate: Timestamp for the last time this commission was modified in our database.

LockingDate: The period of time that the merchants give themselves to reverse or adjust a commission.

MerchantOrderID: Order ID provided by the merchant for this commission. Note:This value may be blank, not every merchant reports an order ID.

MerchantSKU: SKU number for item purchased. Note: This value may be blank, not every merchant reports SKU values.

Retry logic and ensuring against missed records

At the time of the writing of this article, Wildfire does not support retrying failed callbacks. Because of this, we recommend using the API calls (see get all commissions on a regular basis (i.e. hourly) to compensate for the possibility of incomplete callbacks.

Conclusion

Wildfire Systems is trying hard to make merchant data more normalized and though we have tried to standardize around order-item level reporting, some merchants don't provide enough detail to allow us to do that. We are actively considering ways to make the data more normalized, including standardizing around order-level reporting. In the meantime, it's appropriate to design your systems in such a way that they can work with the aforementioned use cases and reach out to us if you have any questions.

Updated01 Jul 2026