For each revenue event, get back relevant data about the entire click to purchase funnel.

🚧

Rate Limiting

This API endpoint is rate limited to 1 request per second

How Date Ranges Work

You can specify commissionDateStart, commissionDateEnd, clickDateStart, and clickDateEnd in the standard 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 do not specify a start date, you will get all transactions up to the specified end date. If you do not specify an end date, you will get all transactions past the start date to present.

📘

Required Fields

A clickDateStart OR a ClickDateEnd is required for each API call.

Valid dates:

clickDateStart=2017/01/01

How Pagination Works

Your first request will return a 4 character reportId. Supply this reportId in the query and each subsequent request will return the next set of results.

📘

Pagination tip

After your initial request, the only parameter that should be present in the api call is the reportId in order to iterate through the results. Adding other parameters will result in an error being generated.

Initial request: https://viglink.io/transactions?clickDateStart=2018/01/01

Second request: https://viglink.io/transactions?reportId=abcd

Which Fields To Use In sumByField

📘

Note on Sums

Adding a sumByField to your query will return all of your transactions, and add an additional node to the end of the results under "buckets" that contains the data and sum. Think of this as a way to return more information for a given query.

  • publisherRevenue
  • orderValue
  • itemQuantity
  • itemPrice

How do I return all commissions earned after July 27, 2017 and return the SUM of the revenue?

For this, we use the clickDateStart parameter to specify 2017/07/27 as the start date and specify publisherRevenue as the value for the sumByField.

<?php
$ch = curl_init("https://viglink.io/transactions?clickDateStart=2017/07/27&sumByField=publisherRevenue");

curl_setopt($ch, CURLOPT_HTTPHEADER, array('Authorization: secret YOUR SECRET KEY'));

curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

$response = curl_exec($ch);

curl_close($ch);
buckets: [
  {
    sumField: "publisherRevenue",
    sumValue: 34274.68,
    fields: { }
  }
]

Which fields to use in groupByFields

📘

Note on Group By's

Adding groupByFields parameter to your query will return all of your transactions, and add an additional node to the end of the results under "buckets" that contains the data grouped as specified. Think of this as a way to return more information for a given query.

The following fields can be used in the groupByFields array:

  • cuid
  • subId
  • campaignName
  • pageUrl
  • anchorText
  • clickUrl
  • clickDate
  • productId
  • productName
  • productSku
  • merchantName
  • merchantId
  • merchantGroupId

A group by might be used to return your top performing merchants, view revenue by page URL, or show you revenue by clickDate.

Specify an array of values that you want to group by, for example for pageUrl and clickDate:

groupByFields=pageUrl,clickDate

How would I view my top performing merchants with a sum of their revenue for a given date range?

We start by specifying our clickDateStart, we follow this with merchantName as the value for our groupByFields, and finally, we specify publisherRevenue in our sumByField.

<?php
$ch = curl_init("https://viglink.io/transactions?clickDateStart=2018/01/01&groupByFields=merchantName&sumByField=publisherRevenue");

curl_setopt($ch, CURLOPT_HTTPHEADER, array('Authorization: secret YOUR SECRET KEY'));

curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

$response = curl_exec($ch);

curl_close($ch);
buckets: [
  {
    sumField: "publisherRevenue",
    sumValue: 712.21,
    fields: {
        merchantName: "iTunes PHG"
    }
  },
  {
    sumField: "publisherRevenue",
    sumValue: 306.45,
    fields: {
        merchantName: "Amazon Marketplace"
    }
  },
  {
    sumField: "publisherRevenue",
    sumValue: 76.67,
    fields: {
        merchantName: "Amazon PGR on SHZ"
    }
  },
  {
    sumField: "publisherRevenue",
    sumValue: 1.43,
    fields: {
        merchantName: "microsoft br"
    }
  },
  {
    sumField: "publisherRevenue",
    sumValue: 1216.06,
    fields: {
        merchantName: "Microsoft Store"
    }
  },
  {
    sumField: "publisherRevenue",
    sumValue: 13.1,
    fields: {
        merchantName: "udemy UK"
    }
  },
  {
    sumField: "publisherRevenue",
    sumValue: 82.98,
    fields: {
        merchantName: "homedepot.com"
    }
  },
  {
    sumField: "publisherRevenue",
    sumValue: 449.05,
    fields: {
        merchantName: "Aliexpress.com International"
    }
  },
  {
    sumField: "publisherRevenue",
    sumValue: 122.71,
    fields: {
        merchantName: "musikhaus thomann cyberstore"
    }
  },
  {
    sumField: "publisherRevenue",
    sumValue: 925.4,
    fields: {
        merchantName: "Lenovo Italy"
    }
  }
]

How Filters Work

The following fields can be used to filter results:

  • campaignIds
  • cuids
  • subIds
  • campaignNames
  • pageUrls
  • anchorTexts
  • clickUrls
  • productIds
  • productNames
  • merchantGroupNames
  • merchantName
  • merchantIds
  • merchantGroupIds

Specify an array of values that you want to search for, for example for productIds, specify:

productIds=product1,product3

Filters are used to narrow down your result set. You might want to filter the results by a specific cuid, subId, or campaign. For example, let's pull back all transactions for a specific campaign:

<?php
$ch = curl_init("https://viglink.io/transactions?clickDateStart=2018/01/01&campaignIds=123456");

curl_setopt($ch, CURLOPT_HTTPHEADER, array('Authorization: secret YOUR SECRET KEY'));

curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

$response = curl_exec($ch);

curl_close($ch);
results: [
  {
    products: [],
    accountId: 123456,
    anchorText: "iOS",
    campaignId: 123456,
    campaignName: "123456",
    clickDate: "2018-01-15",
    clickUrl: "https://itunes.apple.com/br/app/perfil/id688901726?mt=8",
    commissionDate: "2018-01-15"
    commissionId: "1001l1615599542",
    deviceType: "Mobile",
    merchantGroupId: 3,
    merchantId: 62099,
    merchantName: "iTunes PHG",
    merchantNameOriginal: "iTunes PHG",
    orderValue: 0,
    pageTitle: "3 aplicativos de jogo para se divertir com os amigos",
    pageUrl: "http://blog.saldaodainformatica.com.br/dicas-e-aplicativos/3-aplicativos-de-jogo-para-se-divertir-com-os-amigos/",
    publisherRevenue: 0,
    subId: 5096774,
  },
],

🚧

Authorization Header

You must add authorization headers to this request. Please see the Authorization section for further details.

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.

Q: In what case would products 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 will not contain data.

Q: How can I test this in my web browser?
A: You can download a browser extension called mod header here:

https://chrome.google.com/webstore/detail/modheader/idgpnmonknjnojddfkpgkljpfnnfcklj?hl=de

The extension allows you to add a secret key to your request. Under the "Value" section in the plugin, paste "secret 1234abcd" without quotes, and replace the 1234abcd with one of the secret keys from your Commerce account. You can find your secret key in your site settings page:

https://commerce.sovrn.compublisher/sites

Now you can test the API by making a request with your web browser.

example: https://viglink.io/transactions?clickDateStart=2018/01/01

When you are done testing be sure to disable the mod header extension as it can interfere with browsing websites.

Language
Authentication
Header
Click Try It! to start a request and see the response here!