Log in to see full request history

API Overview

The Sovrn Commerce Price Comparison (Affiliated) API allows you to find alternative merchants selling the same product so your readers can compare prices, choose their preferred retailer, automatically update stock availability and prices for specific products, replace out-of-stock product offers with alternate ones, and geo-locate consumers to serve local retailers in local currencies. This will help you increase your click-through rate, conversion rate, and, ultimately, your Commerce revenue by using the provided links.

The API is designed with simplicity in mind. You must provide a product URL from any supported retailer and specify the market area of interest.

This service looks into our system to find all products matching the given criteria.

This is a composite service that performs different searches, starting from the most accurate downwards to the least accurate.

Depending on the provided parameters it starts by seaching by barcode, if barcode is not defined or response is empty tries by plainlink and at last performs a search by keywords.
The service performs the following logic:

IF ( barcode is defined )
response <- searchByBarcode

IF( response is empty and plainlink is defined )
response <- searchByPlainlink

IF( response is empty )
response <- searchByKeywords

return response

Markets

A Market is a currency-language pair (i.e., usd_en) that usually corresponds to the region where the products are sold. The Markets API allows you to list all the available markets from which you can choose Products. Only Markets with at least one available Product are returned. The market code is required as a path value in several API calls.

Markets are encoded as <currency>_<language> (ISO 4217, ISO 639-1). Supported markets:

  • usd_en
  • gbp_en
  • aud_en
  • cad_en
  • eur_de
  • eur_it
  • eur_fr
  • eur_es
  • eur_nl
  • chf_de

Merchants

A Merchant/Retailer is the entity that actually sells the product you wish to advertise, e.g. Amazon, Walmart, John Lewis etc. The Merchants API allows you to list all available merchants in all Markets. Only merchants that sell at least one product in the specified marketplace are returned. Please note that the same merchant may operate in more than one market at the same time.

Price Comparison

The API allows you to search for a specific product in our system and obtain all offers for that product. The results are sorted by price and grouped by merchant (i.e. only the best result for each merchant is returned). It is also possible to apply other filters, such as: price range, filters by merchant, etc.

The API allows you to search by:

barcode

You can choose one of the following: UPC, EAN, GTIN, ISBN and ASIN.

plainlink

Plainlink is the URL of a merchant product web page without tracking parameters (the link as is when browsing the merchant's website).

keywords

It will search for all products that have those keywords in the product title.

Authentication

❗️

Authorization

To query this API, include a Secret Key in the Authorization header of your request. The value of the header must be formatted as secret {SECRET_KEY}, ensuring that the word secret is followed by a space before the key itself.

For details on generating a Secret Key for your site, visit our Authorization guide.

curl --location --request POST 'https://comparisons.sovrn.com/api/affiliate/v3.5/' --header 'authorization: secret {SECRET_KEY}'

Rate Limiting

📘

API Rate Limit

100 requests every 1 second

You can make API requests at a rate of up to 100 requests every 1 second across your entire Sovrn Account. Unless you need to separate request counts by site, we recommend using only one set of keys.

FAQ

How is product data collected?
We collect product data from multiple data sources including, but not limited to, merchant product feeds and merchant APIs.

Is the data normalized or provided as is?
We normalize the data so you don't need to worry about it.

Are images and thumbnails provided?
Yes. We provide URL’s to both full size images and thumbnails as they are sent to us by the merchants through their product feeds.

How fresh is the data?
Depending on the data source, product information is updated from near real-time to once a day.

Why is the data missing or incomplete?

Given the nature of the sources we use to collect product data, some information may be missing or incomplete. There may be several reasons for this. Here are the most common:

  • No information is returned
    • The merchant you are requesting is not supported or is currently unavailable.
    • The product URL you requested is not available through our merchant sources.
  • The information returned is incomplete
    • Some fields (eg. price, stock availability, image, brand) are missing from the merchant feeds
    • No alternative merchants are available since the merchant you requested has not provided the information we need to match alternative offers.
  • The information returned is wrong (eg. wrong price, wrong stock availability, wrong alternative merchant)
    • Merchants have not updated their feeds
    • Merchants have provided wrong data

🚧

Required Field

At least one (barcode, plainlink, or search-keywords) is required for each API call.

Path Params
string
required

The unique identifier of the publishers site.

string
required

The market where to perform the search. Read the market section for the list of supported markets.
For example: 'usd_en' for the US market.

Query Params
string

The barcode of the product to search, can be one of: UPC,EAN,GTIN,ISBN,ASIN.

string
string

List of keywords to search in the product name, separated by space.
For example: 'Dickies hat red' or 'iPhone X'.

string

List of keywords to exclude from the search, separated by space.
Any result matching any of the provided keywords will be stripped out from the results.
For example: 'Dickies hat red' or 'iPhone 10'.

string

Range of prices where the 'salePlace' of the returned products should belong.
The range is defined in the form -, for example 20-30 or 19.9-26.8.
The star can be used to avoid to limit one side of the range, for example -20 equals to 0-20 and 20- will take all results with a sale price >= 20
Note: using *-* is the same as not defining any filter.

integer

Limits the number of results, for example if limit=3 the service will return up to 3 products.
The products in the response will be those from the best performing merchants according to our merchant-ranking system.

string

Custom source ID to be used for tracking purposes. This will be the sovrn CUID.
Can contain only letters, digits, and the following punctuation characters: '-','_','.','~'.
Cannot be longer than 32 characters.

boolean

Sort results by EPC. If true the results will be sorted by EPC otherwise default sorting will be used.

Responses

Language
Credentials
Click Try It! to start a request and see the response here! Or choose an example:
application/json
*/*