Syncing Commission Data via API and Callbacks

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 https //documenter getpostman com/view/24961/rwgqvyv2#5cc69c1d fb39 4231 894e 7acf25487c6f 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 https //docs aws amazon com/prescriptive guidance/latest/cloud design patterns/retry backoff html 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 please contact your client success manager to determine your application's current api version and/or to request an upgrade 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" } } 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) example v3 body without whitespace {"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"} example v4 body without whitespace {"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"} 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 docid\ r4smk3a lbpfbj1l2lurb 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 callback headers the headers for a callback will look like this { "user agent" "wildlink callback bot/1 0", "content length" "412", "cache control" "no cache", "content type" "application/json", "x wf signature" "sha256=c8abc5baf0a109d3365f90b1f783a9f71eaecd1746fcf39b9b4b1b3417b84cca", "accept encoding" "gzip" } note the "x wf signature" value is the hmac encoded value of the post body using a sha256 encoding type and using the callback key value that you set a php example for how to generate this signature (to compare it to the one in the headers to verify that the request is authentic) looks like this $post body = file get contents('php\ //input'); $signature = hash hmac("sha256", $post body, $callback key); note altering the body of the callback sent by wildfire will result in a mismatched signature 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 https //documenter getpostman com/view/24961/rwgqvyv2#5cc69c1d fb39 4231 894e 7acf25487c6f ) on a regular basis (i e hourly) to compensate for the possibility of incomplete callbacks how to get started with commission callbacks if you would like to set up commission callbacks, you may do so via the partner admin under a given application's settings screen navigate to https //platform wildlink me/ select the application you'd like to configure callbacks for select the three dots overflow menu in the top right (see fig 1) select "settings" from the menu input the callback url (this needs to be a full url available to the public) and callback key (this can be any value you choose) you'd like to use (see fig 2) select the callback version you'd like to use (the newest version is usually preferred as it includes more details about each commission record) save note it can take a few minutes before the changes take effect once you set up your callback settings, you'll be able to resend callbacks from the commission history to test your receiving script (see fig 3) order level vs order item level commission records understanding the differences understanding the relationship between orders and commissions is an important part of any partner integration process it allows our partner to track earnings and determine the amount of commission that should be paid to users there are two main types of commission reporting order level and order item level order level commission reporting some merchants provide order level commission reporting, where entire orders are grouped together as a single record in these cases, returns are updated as amounts to the existing commission id the commission id remains the same between the initial and updated records, but the modified date and amounts change here is an example of an order level commission report for an original purchase { "commissionid" 31870476, "applicationid" 104, "merchantid" 5479397, "deviceid" 15319832, "saleamount" { "amount" "60 99", "currency" "usd" }, "amounts" \[ { "amount" "1 2500", "currency" "usd", "splitpart" "application" } ], "status" "pending", "eventdate" "2023 02 02t17 26 55z", "lockingdate" "2023 05 01t05 00 00z", "createddate" "2023 02 02t18 53 58 106991z", "modifieddate" "2023 02 02t18 53 58 106991z", "merchantorderid" "6327180345", "merchantsku" "" } and here is an example of an order level commission report for a partial return { "commissionid" 31870476, "applicationid" 104, "merchantid" 5479397, "deviceid" 15319832, "saleamount" { "amount" "44 96", "currency" "usd" }, "amounts" \[ { "amount" "0 2925", "currency" "usd", "splitpart" "application" } ], "status" "pending", "eventdate" "2023 02 02t17 26 55z", "lockingdate" "2023 05 01t05 00 00z", "createddate" "2023 02 02t18 53 58 106991z", "modifieddate" "2023 03 25t10 44 56 526455z", "merchantorderid" "6327180345", "merchantsku" "" } note that in this case the commissionid and the merchantorderid (aka the order id) stays the same and only the saleamount and amount (aka the commission amount) and modifieddate change to reflect the updated order most merchants, on the other hand, provide order item level commission reporting in this method, every item in an order is posted as a separate commission record items and returns are recorded separately, each with their order item amounts and a separate commission id this method is often referred to as "ledger style " here is an example of an order item level commission report for an original purchase { "commissionid" 32736944, "applicationid" 156, "merchantid" 5479868, "deviceid" 18156054, "saleamount" { "amount" "67 99", "currency" "usd" }, "amounts" \[ { "amount" "1 632", "currency" "usd", "splitpart" "application" } ], "status" "pending", "eventdate" "2023 03 04t21 04 00z", "lockingdate" "0001 01 01t00 00 00z", "createddate" "2023 03 06t15 24 36 611096z", "modifieddate" "2023 03 07t02 57 58 5251z", "merchantorderid" "m2673245040", "merchantsku" "15406898" }, { "commissionid" 32736945, "applicationid" 156, "merchantid" 5479868, "deviceid" 18156054, "saleamount" { "amount" "109", "currency" "usd" }, "amounts" \[ { "amount" "2 616", "currency" "usd", "splitpart" "application" } ], "status" "pending", "eventdate" "2023 03 04t21 04 00z", "lockingdate" "0001 01 01t00 00 00z", "createddate" "2023 03 06t15 24 37 236906z", "modifieddate" "2023 03 07t02 58 07 931103z", "merchantorderid" "m2673245040", "merchantsku" "15453724" } and here is an example of an order item level commission report for a partial return { "commissionid" 33556694, "applicationid" 156, "merchantid" 5479868, "deviceid" 18156054, "saleamount" { "amount" " 109", "currency" "usd" }, "amounts" \[ { "amount" " 2 616", "currency" "usd", "splitpart" "application" } ], "status" "pending", "eventdate" "2023 03 04t21 04 00z", "lockingdate" "0001 01 01t00 00 00z", "createddate" "2023 04 01t23 40 45 361252z", "modifieddate" "2023 04 01t23 40 45 361252z", "merchantorderid" "m2673245040", "merchantsku" "15453724" } order level initial reporting with order item level returns some merchants will describe the initial purchase as a single record but subsequent returns as separate records see below how the initial positive amount (purchase) lists all the skus in a single record but each of two partial returns are reported as separate records { "commissionid" 32753768, "applicationid" 104, "merchantid" 5507506, "deviceid" 15815011, "saleamount" { "amount" "163 6", "currency" "usd" }, "amounts" \[ { "amount" "3 1902", "currency" "usd", "splitpart" "application" } ], "status" "pending", "eventdate" "2023 03 06t23 24 12z", "lockingdate" "2023 05 05t00 00 00z", "createddate" "2023 03 07t01 17 09 578311z", "modifieddate" "2023 03 07t01 17 09 578311z", "merchantorderid" "4042006870", "merchantsku" "99104147967,99104150039,99106898030,99106898040,99106898090,99107014510" } and here is an example of an order item level commission report for a partial return { "commissionid" 32910383, "applicationid" 104, "merchantid" 5507506, "deviceid" 15815011, "saleamount" { "amount" " 31 6", "currency" "usd" }, "amounts" \[ { "amount" " 0 6162", "currency" "usd", "splitpart" "application" } ], "status" "pending", "eventdate" "2023 03 06t23 24 12z", "lockingdate" "2023 05 05t00 00 00z", "createddate" "2023 03 14t12 19 50 66962z", "modifieddate" "2023 03 14t12 19 50 66962z", "merchantorderid" "4042006870", "merchantsku" "99104150039" } 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