--- updatedAt: 2026-03-18T16:55:21.000Z agentTools: projectIndex: https://developer.sovrn.com/llms.txt --- # Product Promo Codes Retrieve ranked, product-specific promo codes with verification status. 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. > ❗️ Registration Required > > Registration is required to access this API. Please contact [Sovrn Support](https://knowledge.sovrn.com/kb/contact-sovrn-support) to request access. > ❗️ 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](https://developer.sovrn.com/docs/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](https://platform.sovrn.com/commerce/settings/site), or retrieve it via the [Campaigns API](https://developer.sovrn.com/reference/campaigns) > * `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 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 by`price_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: ```json "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 same`product_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. # OpenAPI definition ```json { "openapi": "3.0.0", "info": { "title": "Product Coupons API", "version": "1.0.0", "description": "Returns product-specific promo codes for a given retailer product URL. Responses include verified and unverified coupon codes, merchant metadata, and scan status indicating whether verification is in progress.\n" }, "servers": [ { "url": "https://viglink.io/coupons", "description": "Product Coupons API" } ], "paths": { "/product": { "get": { "summary": "Product coupons by URL", "description": "Returns verified and unverified coupon codes for a specific product URL, along with merchant information and verification status.\n", "tags": [ "Product Coupons" ], "security": [ { "SecretKey": [] } ], "parameters": [ { "name": "api_key", "in": "query", "required": true, "description": "Site API key for the site requesting coupons.\n", "schema": { "type": "string" }, "example": "b5d593ce9de90b8a324ca24e5fcc32af" }, { "name": "product_url", "in": "query", "required": true, "description": "Original retailer product page URL. Must not be an affiliate or redirect URL.\n", "schema": { "type": "string", "format": "url" }, "example": "https://www.kiehls.com/3605970407964.html" }, { "name": "include_unverified", "in": "query", "required": false, "description": "Whether to include unverified coupon codes after verified results. Defaults to true.\n", "schema": { "type": "boolean", "default": true }, "example": true }, { "name": "cuid", "in": "query", "required": false, "description": "Custom identifier used to associate the click with a user, page, campaign, or event.\n", "schema": { "type": "string" }, "example": "cuid152" }, { "name": "utm_source", "in": "query", "required": false, "description": "Identifies the source of the traffic (e.g., website, newsletter, twitter).", "schema": { "type": "string" } }, { "name": "utm_medium", "in": "query", "required": false, "description": "Identifies the marketing medium (e.g., email, social, banner).", "schema": { "type": "string" } }, { "name": "utm_campaign", "in": "query", "required": false, "description": "Identifies the campaign name, promotion, or initiative.", "schema": { "type": "string" } }, { "name": "utm_term", "in": "query", "required": false, "description": "Identifies paid search keywords or targeting terms.", "schema": { "type": "string" } }, { "name": "utm_content", "in": "query", "required": false, "description": "Differentiates similar links or placements on the same page.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successfully retrieved coupon code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductCouponsResponse" }, "examples": { "unverifiedExample": { "summary": "Example response with unverified coupons", "value": { "merchant": { "domain": "kiehls.com", "group_id": 2528, "group_name": "Kiehl's", "logo_url": "https://images.viglink.com/merchant/logo/official/240x120/kiehl-s/922daea08e0d6b4e23cf16843bf89e5b5d68d367.png?url=http%3A%2F%2Fwww.viglink.com%2Fmerchants%2F2528.gif&text=Kiehl%27s&logoId=1633" }, "scan": { "verification_active": false, "when_to_check_back": 3600 }, "coupons": [ { "id": "0d5c0846d5430357e07820f153040c36", "code": "WELCOME20", "currency": "USD", "verified": true, "affiliated_url": "https://redirect.viglink.com/...", "original_price": 52, "price_with_code": 41.6, "verified_at": "2026-02-06T15:18:11.746Z", "code_description": null } ] } } } } } }, "400": { "description": "Invalid request parameters." }, "401": { "description": "Unauthorized." }, "404": { "description": "Resource not found." }, "500": { "description": "Internal server error." } } } } }, "components": { "securitySchemes": { "SecretKey": { "type": "apiKey", "in": "header", "name": "Authorization", "description": "Authorization header using the Secret Key scheme. Format: \"secret \".\n" } }, "schemas": { "ProductCouponsResponse": { "type": "object", "required": [ "merchant", "scan", "coupons" ], "properties": { "merchant": { "$ref": "#/components/schemas/Merchant" }, "scan": { "$ref": "#/components/schemas/Scan" }, "coupons": { "type": "array", "description": "Ranked list of coupon codes. Verified coupons appear first, followed by unverified codes.\n", "items": { "$ref": "#/components/schemas/Coupon" } } } }, "Merchant": { "type": "object", "required": [ "domain", "group_id", "group_name" ], "properties": { "domain": { "type": "string", "example": "kiehls.com" }, "group_id": { "type": "integer", "format": "int64", "example": 2528 }, "group_name": { "type": "string", "example": "Kiehl's" }, "logo_url": { "type": "string", "format": "url", "nullable": true } } }, "Scan": { "type": "object", "required": [ "verification_active", "when_to_check_back" ], "properties": { "verification_active": { "type": "boolean", "description": "Indicates whether coupon verification is currently running.\n", "example": false }, "when_to_check_back": { "type": "integer", "format": "int32", "description": "Recommended delay (in seconds) before polling again.\n", "example": 3600 } } }, "Coupon": { "type": "object", "required": [ "id", "code", "affiliated_url", "currency", "verified" ], "properties": { "id": { "type": "string", "description": "Sovrn coupon identifier.", "example": "f556475089750904030e28ad62c6727f" }, "code": { "type": "string", "description": "Promo code text.", "example": "WELCOME20" }, "affiliated_url": { "type": "string", "format": "url", "description": "Affiliate redirect URL with tracking parameters applied.\n" }, "original_price": { "type": "number", "format": "double", "nullable": true, "description": "Original product price.", "example": 52 }, "price_with_code": { "type": "number", "format": "double", "nullable": true, "description": "Final price after applying the code. May be null while verification is in progress.\n", "example": 41.6 }, "currency": { "type": "string", "description": "ISO 4217 currency code.", "example": "USD" }, "verified": { "type": "boolean", "description": "Whether the code has been verified to work.", "example": true }, "verified_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Timestamp when the code was last verified. May be null if not yet verified.\n", "example": "2026-02-06T15:18:11.746Z" }, "code_description": { "type": "string", "nullable": true, "description": "Best-effort description of the promotion. May be null or inaccurate.\n" } } } } } } ```