This endpoint provides product recommendations tailored to your content. Pass in your content along with optional filters like price range or preferred merchants, and receive a curated list of relevant products.
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 APIpageUrl— 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_deMerchants
Merchants are the retailers selling the recommended products (e.g., Walmart, Target). You can:
- Use
includeMerchantsto limit results to specific merchants. - Use
excludeMerchantsto 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%2C67890Pass 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 based on the pageUrl provided in the request.
- If the same
pageUrlis requested multiple times, the cached response may be returned - Products are refreshed hourly to ensure pricing, availability, and other details stay up to date.