Transactions

This endpoint is used to query all commission events (transactions) that have occurred or been updated on a specified date. This data can be used to see individual link performance, actualized earnings, individual site performance and more, all in real-time.

🚧

Authorization

In order to query this API you will need to use a Secret Key in the Authorization header of the request. To learn more about generating a Secret Key for your site, visit our Authorization guide.

🚧

Required Field

At least one date (clickDate, commissionDate, or updateDate) is required for each API call.

Dates

You will need to submit at least one date (clickDate, commissionDate or updateDate) with each call to the API in the format "yyyy-mm-dd" where yyyy is the four digit year, mm is the two digit month and dd is the two digit day. If you specify more than one date in your request, your data will be filtered to only return transactions that meet the date criteria set.

📘

Delta Queries

Looking for only data that has changed or been updated since your last request? Use the updateDate to request all transactions that have been updated on a given day.

Date Range

Each API request is limited to one day of data based on the date supplied in your request. In order to get transactions for a period, call the API for each day you would like to ingest.

Rate Limiting

📘

API Rate Limit

1 request every 60 seconds

You can make API requests at a rate of up to 1 request every 60 seconds. To adhere to this rate limit, include a delay of at least 60 seconds between consecutive calls. Exceeding this rate limit may result in your API key being temporarily blocked or throttled.

For example, if you need to make multiple requests for Transactions across multiple dates, ensure there is a minimum gap of 60 seconds between each request.

Filters

You can filter the response by including one or more of the following query parameters: clickDate, commissionDate,updateDate, campaignIds, merchantGroupIds, programType. The specific field data types are listed below, at the bottom of the page. For an example of specifying multiple filters, see Example of multiple filters below. Note that campaignId and merchantGroupId can also take a comma separated list of numeric ID values.

Campaigns

You can filter the response by campaignIds, or by using multiple campaignIds. To filter by campaignIds, include the campaignIds parameter in the request, followed by the equal sign, followed by one or more campaignIds, separated by commas. For example: campaignIds=1,2,3. The campaignIds must only contain numeric values, greater than 0. The same applies for merchantGroupIds. See Example of filtering by multiple campaignIds below.

To get a list of campaigns, or search for a specific campaign by name, visit our Campaigns reference guide.

Examples

You can use CURL, Postman, Insomnia, Talend, or your favorite REST API tool of choice, in order to make the /reporting/transactions request. Using gzip compression will compress the response, therefore making the response time quicker. Note that the response will always be in JSON format.

A CURL example executed from the command line, using gzip compression and writing the response to a file named commerce-txn-reporting.json would be:

curl --request GET --location 'https://viglink.io/v1/reports/transactions?clickDate=2023-01-01' \
--header 'Authorization: secret <your_secret_key_here>' \
--header 'Accept-Encoding: gzip' --compressed > commerce-txn-reporting.json

Example without gzip compression:

curl --request GET --location 'https://viglink.io/v1/reports/transactions?clickDate=2023-01-01' \
--header 'Authorization: secret <your_secret_key_here>' > commerce-txn-reporting.json

Example of multiple filters:

curl --request GET --location 'https://viglink.io/v1/reports/transactions?clickDate=2023-01-01&updateDate=2023-01-02&campaignIds=100&merchantGroupIds=78910&programType=CPC'  \
--header 'Authorization: secret <your_secret_key_here>' \
--header 'Accept-Encoding: gzip' --compressed > commerce-txn-reporting.json

Example of filtering by multiple campaignIds:

curl --request GET --location 'https://viglink.io/v1/reports/transactions?clickDate=2023-01-01&updateDate=2023-01-02&campaignIds=100,200,300&merchantGroupIds=78910&programType=CPC'  \
--header 'Authorization: secret <your_secret_key_here>' \
--header 'Accept-Encoding: gzip' --compressed > commerce-txn-reporting.json

Example of filtering by multiple merchantGroupIds:

curl --request GET --location 'https://viglink.io/v1/reports/transactions?clickDate=2023-01-01&updateDate=2023-01-02&campaignIds=100&merchantGroupIds=70,80,90,100&programType=CPA'  \
--header 'Authorization: secret <your_secret_key_here>' \
--header 'Accept-Encoding: gzip' --compressed > commerce-txn-reporting.json

Example response, with a single campaignId:

{"transactions":[{"account":{"accountId":1234,"campaignId":1,"campaignName":"Awesome Stuff"},"commission":{"revenueId":"123456","commissionId":"abcd1234","commissionDate":"2023-01-01","updateDate":"2023-01-13","orderValue":0,"publisherNetRevenue":0.0075,"programType":"cpc"},"click":{"clickId":"defg1234","clickDate":"2023-01-01","cuid":"","linkUtmInfo":{"utmSource":"","utmMedium":"","utmCampaign":"","utmTerm":"","utmContent":""},"pageUtmInfo":{"utmSource":"","utmMedium":"","utmCampaign":"","utmTerm":"","utmContent":""},"pageUrl":"www.awesome-stuff.com/","linkUrl":"awesome.click/abc123?campaignid=1","sovrnProduct":"Link","country":"us","device":"Mobile"},"merchant":{"merchantGroupId":56789,"merchantGroupName":"AwesomeSauce","network":"Sovrn"},"product":[]}]}

FAQ

Q: If one of my readers returns their purchase, how will this show?
A: Depending on the data we get back from our network partners, the return may show either as an adjustment to the original transaction or as a new separate transaction. Utilizing updateDate to query what data has changed will capture both types of adjustments.

Q: In what case would product array be empty, and have data?
A: The product array will return information about the products purchased as part of the transaction. Not all merchants and networks provide this information, so you may see an empty array when not available.

Q: deviceType is sometimes not showing, why?
A: We don't always have access to detailed information about the click, or there may be instances where we are unable to accurately determine the device type.

Q: what are all the possible values for deviceType?
A: Mobile, Desktop, and Tablet

Q: clickUrl, pageUrl, and pageTitle are sometimes not showing, is this expected?
A: We don't always have detailed information about the click that leads to a conversion. In these instances, some of the fields related to the click may be empty.