The Promo Codes API returns product-specific deals based on a retailer's product URL. By passing in a product page — whether from a major retailer or an approved merchant — the API returns verified and unverified codes, along with verification status and scan metadata.

Each response includes merchant information, current verification state, and affiliate-ready URLs with tracking parameters applied. Verified codes are returned first, followed by unverified candidates when enabled.

This makes it easy to surface working promo codes in shopping surfaces, deal modules, and other commerce experiences — all with a single API call.

❗️
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.

🚧
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 Campaigns API

productURL — The raw URL of the product you want coupons for. This should be the original retailer product page and not an affiliate or redirect URL. Use a canonical, stable URL whenever possible to ensure consistent results and caching behavior.

Optional Parameters

You can include additional parameters to improve tracking and reporting. These values are appended to the affiliate redirect URL returned in the response.

Field	Description
`include_unverified`	Whether to include unverified promo codes after verified results. Default is true. Disable this to return only verified codes.
`cuid`	An identifier of your choosing used to associate the click with a user, page, campaign, or event. Maximum 2048 alphanumeric characters.
`utm_source`	Identifies the source of the traffic (e.g., website, newsletter, X).
`utm_medium`	Identifies the marketing medium (e.g., email, social, banner).
`utm_campaign`	Identifies the campaign name, promotion, or initiative (e.g., black_friday_2025).
`utm_term`	Identifies paid search keywords or targeting terms.
`utm_content`	Differentiates similar links or placements on the same page (e.g., header, footer).

Example Request

curl --location "https://viglink.io/coupons/product?api_key=YOUR_API_KEY&product_url=https%3A%2F%2Fwww.kiehls.com%2Fskincare%2Fface-moisturizers%2Fultra-facial-cream-with-squalane%2F622.html&include_unverified=true&cuid=example123&utm_campaign=test" \
  --header "Authorization: secret YOUR_SECRET_KEY"

Code Ranking

Codes are returned in a deterministic order:

Verified codes appear first and are sorted byprice_with_code when available.
Unverified codes follow and are sorted by estimated discount.

If final pricing cannot be retrieved, estimated discounts may be used for ordering.

Verification & Scan Status

Some products require active discovery and verification before reliable results are available. In these cases, the response includes scan metadata:

"scan": {
  "verification_active": true,
  "when_to_check_back": 3600
}

This indicates that verification is in progress and the client should retry after the specified interval (in seconds).

Partial or interim results may be returned while verification is running.

Nullable Fields

Some response fields may be null while verification is in progress, including:

price_with_code
verified_at (ISO 8601, UTC)
code_description

Caching

To improve performance, responses are cached internally by product_url.

Each request first checks the cache:

If a cached result is available, it is returned immediately.
If no cached result is available, an empty or partial response may be returned while code discovery and verification runs in the background.

When a cache miss occurs, the product is processed asynchronously and the cache is populated once results are available. Subsequent requests for the sameproduct_url will return updated data.

Requests using the same product_url may return cached results until refreshed.

If verification_active is true, clients should use when_to_check_back to determine when to poll for updated results.

To improve cache utilization:

Use canonical product URLs.
Avoid including session or tracking parameters.
Reuse consistent URLs for the same product.
Products that are not requested regularly may pause refresh until queried again.