API Overview

The Product Recommendation API utilizes AI content recognition to help publishers surface contextually relevant products based on their content. By passing in content — whether that’s a full page, a snippet, or a simple description — the API returns a curated list of shoppable products from Sovrn’s affiliate network.

This makes it easy to personalize on-page shopping experiences, build dynamic product carousels, populate newsletters, or create custom gift guides — all with a single API call.

❗️
Authorization
To query this API, include your site API key as the query parameter apiKey. This key is specific to the site you want to generate product recommendations for.
You can find your key in the Sovrn Platform under Site Settings, or retrieve it via the Campaign API.

🚧
Required Fields
Each request must include:

apiKey — Your API key for the site you want to generate recommendations for. This can be found in the Sovrn Platform under Site Settings, or retrieve it via the Campaign API

pageUrl — The URL associated with the content you’re sending. This can be the actual page URL or a placeholder if the content is not tied to a specific page.

content — The content you want to generate product recommendations for. This could be HTML from a page, plain text from an article, or even a description of a user or event.

Optional Fields

You can customize the recommendations returned using the following optional fields:

Field	Description
`title`	A short, descriptive title for the content. Helps provide context to the model, but not required.
`market`	Market identifier in the format currency_language (e.g., usd_en). Determines local currency and language. If not provided, it will be inferred from IP address.
`cuid`	Custom tracking ID for associating recommendations with a specific page, user or session.
`priceRange`	Filter results by price, using formats like "20-50", "-25", or "100-" for open-ended ranges.
`includeMerchants`	List of merchant IDs to include. Only products from these merchants will be returned.
`excludeMerchants`	List of merchant IDs to exclude from results.
`numProducts`	Number of products to return. Default is 4, max is 50.

Markets

Markets define the currency and language for the product recommendations. Use the market parameter to explicitly set a market. If omitted, we’ll automatically detect the user’s region based on their IP address.

Supported Markets:

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

Merchants

Merchants are the retailers selling the recommended products (e.g., Walmart, Target). You can:

Use includeMerchants to limit results to specific merchants.
Use excludeMerchants to omit merchants from your results.

Merchant IDs can be retrieved using the Approved Merchants API. Use the value from the groupID field in the response to identify each merchant.

⚠️ You can only use one of these filters (includeMerchants or excludeMerchants) in a single request. Using both at the same time is not supported.

Example usage:

...?includeMerchants=12345%2C67890

Pass a URL-encoded, comma-separated list of merchants to apply either filter.

Rate Limiting

The Product Recommendation API is rate-limited to ensure performance and stability across all users. There are two limits to be aware of:

API Key Limit

30,000 requests per 5 minutes
This is the primary limit for most server-side use cases and should be sufficient for high-scale implementations.

IP-Based Limit

100 requests per 5 minutes per IP address
This may impact high-volume server-side implementations where requests come from a single IP (e.g., behind a proxy or load balancer)

Caching

To improve performance and reduce latency, responses are cached by the exact pageUrl value provided in the request. Any request using the same pageUrl will return the same cached response until the cache expires.

To make the most of caching and avoid unexpected results, follow these guidelines when setting the pageUrl field:

Use a stable slug or the actual page URL: Examples include mens_shoes, running-shoes, summer-sandals, or /products/mens/shoes. Consistency is key — using the same value across requests ensures cache hits and predictable responses.
One piece of content per pageUrl: Each pageUrl should represent a single piece of content (e.g., a page, article, or prompt). If you need different cached results (e.g., “budget men’s shoes” vs. “premium men’s shoes”), assign each one its own key, such as mens_shoes_budget and mens_shoes_premium.
Don’t put content in pageUrl: Keep natural-language prompts, descriptions, or full page text in the content field. The pageUrl should act only as a stable identifier for the piece of content.