API Implementation with Commerce

If you're already using our publisher platform to monetize your site you can streamline the process using our API.

đź“„ Note:

Please find complete documentation for all Sovrn Commerce APIs here.

Sovrn Commerce offers a variety of APIs.

Each has its own documentation in the developer center, along with configuration and authorization instructions.

Please note that all sites/apps/toolbars/etc that you hope to use will need to be approved  by Sovrn's Network Quality team in order for you to affiliate with our merchant partners. 

Skip to Section: 

Where can I find my API key & Secret Key?

Are there rate limits for any of the APIs? 

How do I create an an alias for Sovrn Commerce API Calls?

Does aliasing work with SSL?

How can I easily test out the Commerce API?

I still need help. 

How to find your site's API key & Secret key

Both your API key and your secret key can be found on the Site configuration tab of your Sovrn Commerce account. Clicking on the "key" icon in the row for each site will show the associated API key. Here, you will also have the option to generate a secret key which will allow you to use some of our API tools. 

Note: Your secret key can be used to pull all of your account data, and you will not need a secret key for each of your sites. When using the Secret Key with the Sovrn Commerce APIs, use the word "secret" along with your secret key. That is, "secret 1234" rather than just "1234". You can read more about authorization here.

Are there rate limits for any of the APIs? 

The Transaction Reporting API and the Product Metadata API are the only two API tools that have a rate limit in place, each at one request per second.
Please also check the complete API documentation for more information. 

There are not currently any API limits in place for the other tools, but that could always change in cases of abuse.


Aliasing Sovrn Commerce API Calls

You can mask the fact that you use Sovrn Commerce's affiliation services by creating "alias" domains for Sovrn's service-related hostnames, and making a slight modification to your Sovrn JavaScript library initialization parameters.

Any publisher can alias the API calls by creating a single CNAME and redirecting Sovrn API calls to that name.

To create the appearance that a page on your website calls publisher-provided services instead of Sovrn Commerce's service, use the following guidelines:

  • Create a DNS CNAME that points to api.viglink.com. We suggest using click.<publisherdomain>.com
  • Change the api_url parameter in the Sovrn Javascript library initialization code on your pages to specify the alias domain name.

 An example altered initialization block is shown below:

<script type="text/javascript">

  var vglnk = { api_url: '//click.mydomain.com/api',

                key: 'mypublisherkey' };

   (function(d, t) {

    var s = d.createElement(t); s.type = 'text/javascript'; s.async = true;

    s.src = ('https:' == document.location.protocol ? vglnk.api_url :

             '//cdn.viglink.com/api') + '/vglnk.js';

    var r = d.getElementsByTagName(t)[0]; r.parentNode.insertBefore(s, r);

  }(document, 'script'));

</script> 

A Note About SSL

These instructions apply primarily to non-SSL traffic. Aliasing SSL traffic is more complex because of the security protocols involved. Sovrn does not currently support aliasing its hostnames for SSL (https) traffic.

If your site supports SSL, the code snippet below will function—but viewers accessing the publisher site via SSL will see warnings in their browser.

<script type="text/javascript">

var vglnk = { api_url: '//click.mydomain.com/api',

                key: 'mypublisherkey' };

   (function(d, t) {

    var s = d.createElement(t); s.type = 'text/javascript'; s.async = true;

    s.src = ('https:' == document.location.protocol ? vglnk.api_url :

             '//clickcdn.mydomain.com/api') + '/vglnk.js';

    var r = d.getElementsByTagName(t)[0]; r.parentNode.insertBefore(s, r);

  }(document, 'script'));

</script>

 

How can I easily test out the Commerce API?

Let’s say you want to see the type of information the API gives you, if the data is what you’re looking for, how it would look, or even, how to use it before deciding if it’s the API you will use.

Luckily, we have a “Try it Out” section that requires zero coding at all -- just some information that can be found in your Sovrn account settings.

With most of our API Documentations, there will be a “Try it Out” section located at the very bottom of the page. In these sections, you can test to see exactly what information will be provided, the different filters or parameters that you can use, and of course, the results itself.

Here’s a link to our API Documentation.

Before diving in, let’s find out where you can locate the two kinds of information that is crucial to “Test it Out”. The two kinds of information needed is API Key and Secret Key.

See how to find your keys above

**Do not share your Secret Key**

Next, let’s take a look at the Sovrn Transaction Report API documentation.

Scroll to the bottom of the page and you’ll see:

commerce-api-and-developer-center-2

This is the area where you’ll be placing your Secret Key. Click on the green key icon and a field will appear for you to type in your Secret Key. The format of how this should be typed is the word “secret”(without quotations), then a space, and then your Secret key. So, it should look something like this:

secret 123yoursecretkey123

commerce-api-and-developer-center-3

  1. In order to run this “Try it Out”, you’ll need the minimum of these two fields, which is what the red asterisks are denoting. The date format should be YYYY/MM/DD.

Press “Try it” below all the field boxes and that’s it! You should see your results in a window:

commerce-api-and-developer-center-4

Now that you have the basics, you’ve might’ve noticed the other boxes with fields you can fill in. These are the different parameters you can use to be more specific with the data being returned. These parameters are outlined at the top of API documentation to let you know what type of information it is.

Using the same Transaction API with the same dates, try searching for a “merchantName”.

Please note that the format and punctuation have to be exactly what we have in our system. So we recommend running a basic call as we did above to familiarize yourself with the format the results are in. 

For example, if we want to filter down by Walmart, we’ll have to type it in the field exactly how we saw it in the report:

commerce-api-and-developer-center-5

commerce-api-and-developer-center-6

Press “Try It” and it will only return results with the merchant name “Walmart”.

This strategy will work for the other parameters in this Transaction API or another API you decide to “Try it Out”. Using the results from the initial data return, you can learn what the field is looking for and how to fill it in to narrow down your dataset to get exactly what you’re looking for.

I still need help. 

If you still need help, please check the complete API documentation here, or reach out to Sovrn Support.