Merchants API

The Merchants API is the main interface for publishers wishing to know statistics about the merchants on our network. The Merchants API returns all merchants that Skimlinks works with. All values should be url encoded. For instance, if you are searching for "Best Buy", the phrase "Best Buy" should be encoded to Best%20Buy.

Changelog

0.3

2012-03-06 - Merchants and Product (EveryFeed) are now separate APIs.

0.4

2012-09-11 - Add Categories to 'search' call

API Endpoint

The Merchant API endpoint is:

http://api-merchants.skimlinks.com/merchants/

API Methods

The Merchants API consists of the following methods:

Get category information (/categories)

Retrieve a list of our Merchant categories. Use in conjunction with the /category call to get a list of the merchants in a specific category.

Endpoint

http://api-merchants.skimlinks.com/merchants/categories

Fields	Description
key required	Public API key - `char(32)`
format required	The format of the returned results, either `xml` or `json`.

Example API Call / Response

XML

JSON

GET

Example Call

Returns all category information including the IDs. Any child categories are listed in a `children` element.

http://api-merchants.skimlinks.com/merchants/xml/aabbccddeeffgghhiijjkk1122334455/categories

XML Response

<?xml version="1.0" encoding="UTF-8"?>
<skimlinksCategories>
    <category>
        <id>1</id>
        <name>adult &amp; mature</name>
    </category>
    <category>
        <id>2</id>
        <name>arts, crafts &amp; hobbies</name>
    </category>
    <category>
        <id>3</id>
        <name>automotive, cars &amp; bikes</name>
    </category>
    <category>
        <id>4</id>
        <name>baby &amp; parenting supplies</name>
    </category>
    <category>
        <id>5</id>
        <name>books &amp; magazines</name>
    </category>
<skimlinksCategories>

Get Merchant Domain Information (/domains)

Retrieve a list of domains for the Merchants we work with.

Endpoint

http://api-merchants.skimlinks.com/merchants/domains

Fields	Description
key required	Public API key - `char(32)`
format required	The format of the returned results, either `xml` or `json`
start optional	The index from which to start returning results. (defaults to 0) - `int`
limit optional	Number of results to return - `int`

Example API Call / Response

XML

JSON

GET

Example Call

Return 1 merchant domain, starting from the 100th domain.

http://api-merchants.skimlinks.com/merchants/xml/aabbccddeeffgghhiijjkk1122334455/domains/limit/1/start/100

XML Response

<?xml version="1.0" encoding="UTF-8"?>
<skimlinksMerchantsDomains version="0.4">
  <timeStamp>2012-03-12T15:36:49+00:00</timeStamp>
  <numFound>23094</numFound>
  <numStarted>100</numStarted>
  <numReturned>1</numReturned>
  <domains>
    <domain id="23380">neogie.com</domain>
  </domains>
</skimlinksMerchantsDomains>

Search merchant and categories (/search)

This method returns information about merchants and categories that match the supplied search term. The search term is matched against merchant name and domain, and category name.

Endpoint

http://api-merchants.skimlinks.com/merchants/search

Fields	Description
search required	The merchant to search for - `string`
key required	Public API key - `char(32)`
format required	The format of the returned results, either `xml` or `json`
start optional	The index from which to start returning results. (defaults to 0) - `int`
limit optional	Number of results to return - `int`
filter_by optional	Set to `preferred` to only return merchants who are part of the Skimlinks Preferred Partner Program. Should be set as a query param e.g. `?filter_by=preferred`

Example API Call / Response

XML

JSON

GET

Example Call

Searching for the word 'Con' limiting the result set to two.

http://api-merchants.skimlinks.com/merchants/xml/aabbccddeeffgghhiijjkk112233445566/search/con/limit/2/start/0?filter_by=preferred

XML Response

<?xml version="1.0" encoding="UTF-8"?>
<skimlinksMerchants version="0.4">
    <timeStamp>2012-09-12T14:05:37+01:00</timeStamp>
    <numFound>8</numFound>
    <numStarted>0</numStarted>
    <numReturned>2</numReturned>
    <merchants>
        <merchant>
            <dateUpdated>2012-09-11T00:02:00+01:00</dateUpdated>
            <merchantID>9643</merchantID>
            <preferred>
                <ecpc>0.00</ecpc>
                <featuredCommission>5.000</featuredCommission>
                <commissionDetails><![CDATA[Was 3% --&gt; NOW 5% + $50.00 Palm Purchase!!
(2% third party)]]></commissionDetails>
                <commission><![CDATA[5% (2% third party) + $50.00 Palm Purchase]]></commission>
                <description><![CDATA[The HP Home &amp; Home Office Store, Hewlett-Packard&#039;s direct-to-consumer e-commerce business, offers U.S. customers a one-stop shop for HP products including customized HP Pavilion and Compaq Presario PCs, handheld devices, printers, printing supplies and digital entertainment products.]]></description>
            </preferred>
            <merchantName>HP Home &amp;amp; Home Office Store</merchantName>
            <averageConversionRate>0.17%</averageConversionRate>
            <averageCommission>4.95%</averageCommission>
            <logo>http://s.skimresources.com/logos/9643.gif</logo>
            <domains>
                <domain>
                    <domainID>91710</domainID>
                    <domainName>falconpro.fc.hp.com</domainName>
                </domain>
            </domains>
            <categories/>
        </merchant>
        <merchant>
            <dateUpdated>2012-09-11T00:02:00+01:00</dateUpdated>
            <merchantID>24926</merchantID>
            <preferred>
                <ecpc>0.00</ecpc>
                <featuredCommission>12.000</featuredCommission>
                <commissionDetails><![CDATA[Was 9% --&gt; NOW 12%!!]]></commissionDetails>
                <commission><![CDATA[12%]]></commission>
                <description><![CDATA[Convenient Gadgets is an online retailer offering unique gadgets to customers throughout North America. The company prides itself in finding unique gadgets that you can&rsquo;t find just anywhere and make great personal or gift purchases. ]]></description>
            </preferred>
            <merchantName>Convenient Gadgets &amp;amp; Gifts, LLC</merchantName>
            <averageConversionRate>2.58%</averageConversionRate>
            <averageCommission>7.29%</averageCommission>
            <logo>http://s.skimresources.com/logos/24926.jpg</logo>
            <domains>
                <domain>
                    <domainID>22428</domainID>
                    <domainName>cgets.com</domainName>
                </domain>
            </domains>
            <categories>
                <category id="33">gifts</category>
            </categories>
            <countries>
                <country>united states</country>
            </countries>
        </merchant>
    </merchants>
    <categories>
        <category>
            <id>8</id>
            <name>consumer electronics</name>
            <merchantCount>870</merchantCount>
            <children>
                <category>
                    <id>9</id>
                    <name>audio, tv &amp; home theatre</name>
                    <merchantCount>598</merchantCount>
                </category>
                <category>
                    <id>10</id>
                    <name>cameras &amp; photos</name>
                    <merchantCount>741</merchantCount>
                </category>
                <category>
                    <id>11</id>
                    <name>gadgets &amp; geeks</name>
                    <merchantCount>748</merchantCount>
                </category>
                <category>
                    <id>12</id>
                    <name>mobiles, pdas &amp; satnav</name>
                    <merchantCount>788</merchantCount>
                </category>
                <category>
                    <id>13</id>
                    <name>mp3 players &amp; accessories</name>
                    <merchantCount>683</merchantCount>
                </category>
            </children>
        </category>
    </categories>
</skimlinksMerchants>

Example Call

Searching for the word 'Con' limiting the result set to two.

http://api-merchants.skimlinks.com/merchants/json/aabbccddeeffgghhiijjkk1122334455/search/con/limit/2/start/0?filter_by=preferred

JSON Response

{
  "timeStamp": "2012-09-12T12:38:42+01:00",
  "numFound": 8,
  "numStarted": "0",
  "numReturned": "2",
  "merchants": [
    {
      "preferred": {
        "commission": "5% (2% third party) + $50.00 Palm Purchase",
        "commissionDetails": "Was 3% --&gt; NOW 5% + $50.00 Palm Purchase!!\r\n(2% third party)",
        "description": "The HP Home &amp; Home Office Store, Hewlett-Packard&#039;s direct-to-consumer e-commerce business, offers U.S. customers a one-stop shop for HP products including customized HP Pavilion and Compaq Presario PCs, handheld devices, printers, printing supplies and digital entertainment products.",
        "ecpc": "0.00",
        "featured_commission": "5.000"
      },
      "dateUpdated": "2012-09-11T00:02:00+01:00",
      "merchantID": "9643",
      "merchantName": "HP Home & Home Office Store",
      "averageConversionRate": "0.17%",
      "averageCommission": "4.95%",
      "logo": "http:\/\/s.skimresources.com\/logos\/9643.gif",
      "domains": {
        "91710": "falconpro.fc.hp.com"
      },
      "categories": [
      ]
    },
    {
      "preferred": {
        "commission": "12%",
        "commissionDetails": "Was 9% --&gt; NOW 12%!!",
        "description": "Convenient Gadgets is an online retailer offering unique gadgets to customers throughout North America. The company prides itself in finding unique gadgets that you can&rsquo;t find just anywhere and make great personal or gift purchases. ",
        "ecpc": "0.00",
        "featured_commission": "12.000"
      },
      "dateUpdated": "2012-09-11T00:02:00+01:00",
      "merchantID": "24926",
      "merchantName": "Convenient Gadgets & Gifts, LLC",
      "averageConversionRate": "2.58%",
      "averageCommission": "7.29%",
      "logo": "http:\/\/s.skimresources.com\/logos\/24926.jpg",
      "domains": {
        "22428": "cgets.com"
      },
      "categories": {
        "33": "gifts"
      },
      "countries": [
        "united states"
      ]
    }
  ],
  "categories": {
    "8": {
      "id": "8",
      "merchant_count": "870",
      "name": "consumer electronics",
      "children": {
        "9": {
          "id": "9",
          "merchant_count": "598",
          "name": "audio, tv & home theatre"
        },
        "10": {
          "id": "10",
          "merchant_count": "741",
          "name": "cameras & photos"
        },
        "11": {
          "id": "11",
          "merchant_count": "748",
          "name": "gadgets & geeks"
        },
        "12": {
          "id": "12",
          "merchant_count": "788",
          "name": "mobiles, pdas & satnav"
        },
        "13": {
          "id": "13",
          "merchant_count": "683",
          "name": "mp3 players & accessories"
        }
      }
    }
  }
}

Get Merchant Category Information (/category)

Returns information about merchants in a particular category. Use in conjunction with the /categories call to get a list of the Category IDs to use with /category call.

Endpoint

http://api-merchants.skimlinks.com/merchants/category

Fields	Description
key required	Public API key - `char(32)`
format required	The format of the returned results, either `xml` or `json`
start optional	The index from which to start returning results. (defaults to 0) - `int`
limit optional	Number of results to return - `int`
filter_by optional	Set to `preferred` to only return merchants who are part of the Skimlinks Preferred Partner Program. Should be set as a query param e.g. `?filter_by=preferred`

Example API Call / Response

XML

JSON

GET

Example Call

Return the first merchant in the category 'Arts, Crafts & Hobbies'

http://api-merchants.skimlinks.com/merchants/xml/aabbccddeeffgghhiijjkk1122334455/category/2/limit/1

XML Response

<?xml version="1.0" encoding="UTF-8"?>
<skimlinksMerchants version="0.4">
  <timeStamp>2012-03-12T15:20:52+00:00</timeStamp>
  <numFound>313</numFound>
  <numStarted>0</numStarted>
  <numReturned>1</numReturned>
  <merchants>
    <merchant>
      <dateUpdated>2012-03-11T00:02:00+00:00</dateUpdated>
      <merchantID>17751</merchantID>
      <merchantName>123Posters.com, Inc.</merchantName>
      <averageConversionRate>0</averageConversionRate>
      <averageCommission>0</averageCommission>
      <logo>
        http://skimlinks.com/images/merchantlogos/17751.jpg
      </logo>
      <domains>
      <domains>
        <domain>
        <domainID>9695</domainID>
        <domainName>123posters.com</domainName>
        </domain>
      </domains>
      <categories>
        <category id="10">consumer electronics;cameras &amp; photos</category>
        <category id="8">consumer electronics</category>
        <category id="47">music, mp3 &amp; movies</category>
        <category id="2">arts, crafts &amp; hobbies</category>
      </categories>
      <countries>
        <country>united states</country>
      </countries>
    </merchant>
  </merchants>
</skimlinksMerchants>

API Documentation

Table of Contents

Merchants API

Changelog

0.3

2012-03-06 - Merchants and Product (EveryFeed) are now separate APIs.

0.4

2012-09-11 - Add Categories to 'search' call

API Endpoint

API Methods

Get category information (/categories)

Endpoint

Example API Call / Response

GET

Example Call

XML Response

Example Call

JSON Response

Get Merchant Domain Information (/domains)

Endpoint

Example API Call / Response

GET

Example Call

XML Response

Example Call

JSON Response

Search merchant and categories (/search)

Endpoint

Example API Call / Response

GET

Example Call

XML Response

Example Call

JSON Response

Get Merchant Category Information (/category)

Endpoint

Example API Call / Response

GET

Example Call

XML Response

Example Call

JSON Response