Skip to main content

Sponsored Product Ads

What is a Sponsored Product Ad?​

Sponsored Product Ads are native ads that promote individual products within the shopping experience. They appear alongside organic listings on search results or category pages, looking like regular products but marked as sponsored.

Each ad uses the product’s own title, image, price, and details to match the shopper’s context—for example, showing a sponsored laptop on a “laptops” search page.

Only synced and active products in GoWit’s system can be shown. If a product isn’t loaded or is inactive, it can’t be served.

This format is key for driving direct sales, connecting a shopper’s intent (search or browse) directly to a product offer while blending naturally into the marketplace experience.

Required Fields for Sponsored Product Ad Requests​

Every ad request for a Sponsored Product must include certain key parameters to identify the placement and user session, ensuring the platform can return a suitable product ad and track it properly. The required fields include:

  • Marketplace ID (marketplace_id) – The unique identifier of your marketplace in GoWit’s system. This tells the ad server which marketplace’s data and campaigns to use for the request. It ensures that the ad comes from the correct environment (so you don’t, for example, see another marketplace’s products). This ID is typically provided in your API credentials or configuration. Business purpose: It scopes the request to your integration, loading the relevant advertisers, products, and campaigns. Without the correct marketplace_id, the platform wouldn’t know what inventory or rules to apply, and the request will fail.

  • Placement ID (placement_id) – The numeric ID of the ad placement slot where the sponsored product will be displayed. This is obtained from GoWit when you configure ad placements (e.g. a placement ID for “Search Results – Sponsored Product Slot 1”). Business purpose: The placement_id routes the ad request to campaigns targeting that specific slot/location on your site. It ensures the ad server only considers campaigns eligible for that placement (correct format and context). Using the correct placement_id is crucial – it links the request to the right set of ads. If the placement_id is wrong or missing, no valid ads will be returned for that slot.

  • Session ID (session_id) – A stable and unique identifier for the user across the attribution window (not a short, expiring “browser session” token). Include it in every ad request and all events. Business purpose: The session_id is used for attribution and frequency control. It ties the delivered ad to the user’s session so that any impressions, clicks, or conversions can be attributed back to this ad view—so it must remain persistent across page views, reloads, and even browser restarts (store via first-party cookie, localStorage or persistent storage). In other words, session_id allows GoWit to track that “User session X saw Ad Y and later purchased Product Z.” This is critical for measuring performance (conversions, ROAS) and for enforcing any per-session limits (like not showing the same ad too many times). Always provide a consistent session_id for a user across pageviews to avoid breaking attribution chains.

  • Ad Context – Contextual fields that inform the ad server about the current page and user intent. While not always “mandatory” in the API request schema, these are essential for relevance in Sponsored Product ads and should be provided whenever available:

    • Search Term (search) – The search query the user entered (if on a search results page). For example, “wireless headphones”. Business purpose: The ad engine uses this to match ads to user intent. Campaigns in GoWit can target keywords, so providing the search term allows the system to select product ads that are keyword-relevant. If you omit the search term on a search page, the platform loses a major signal – you may get less relevant ads or miss out on keyword-targeted sponsored products that should appear.
    • Category (category or category_id) – The category context if the user is browsing a category or listing page. This can be a human-readable taxonomy path ("Electronics > Mobile Phones") or a category ID code used in your system. Business purpose: This tells GoWit what category the user is looking at, so it can filter/select ads accordingly. Many Sponsored Product campaigns target specific categories (or choose not to show in certain categories). By providing the category, you ensure that the returned sponsored products align with the page content (e.g. only showing products from the “Mobile Phones” category when the user is browsing phones). If not provided, GoWit will try to infer context (for instance, from any product list you send), but explicit category input is more reliable for relevance.
    • Visible Products (products list) – An array of product identifiers that are currently visible on the page organically (e.g., the top N items on a search or category page). Each entry should include the product’s id and, when available, the product’s category. Business purpose: provides the ad server with page context (what the shopper is looking at) to improve relevance. Including category directly in each item is recommended: Supplying category up front reduces the latency and helps the server evaluate relevance faster. While not strictly required by the API, it is highly recommended to send for search/category pages. (On pages like the homepage where there is no product list, you can omit it.) Make sure the IDs you send here match the ones used in your product feed – otherwise the system can’t recognize them.

  • Page Number (page_number) – Required for any paginated context (e.g., search or category listings). Use zero-based indexing: the first page is 0, the second page is 1, etc. Business purpose: enables pagination-aware ad delivery so users aren’t shown the same ads again on subsequent pages, improving browsing experience across page transitions. Always include page_number on every eligible request; omit it only on non-paginated views (e.g., homepage).

Optional Fields and Their Importance – Sponsored Product Ads​

In addition to the core fields above, the Sponsored Product request can include optional parameters that enhance targeting and attribution. While not strictly required to get an ad, they can improve the results or ensure proper campaign filtering. Here are the optional fields and why they matter:

  • Max Ads (max_ads) – (Optional; default comes from the placement configuration.) Determines the maximum number of ads the server will return for a request. The effective limit is calculated against the placement’s configured maximum:

    Let placementMax = adPlacement.MaxAds().

    If adRequest.MaxAds is set (request-level), then effectiveMax =
    min(adRequest.MaxAds, placementMax).

    Else, if you’re using v2 and adRequest.Placements[i].MaxAds is set
    (per-placement), then effectiveMax = min(adRequest.Placements[i].MaxAds,
    placementMax).

    Else, effectiveMax = placementMax.

    Implications & guidance

    • The placement’s MaxAds is an upper bound; a request can only lower it, never raise it.
    • The server may still return fewer than effectiveMax (e.g., limited eligible inventory/targeting).
    • Only request as many ads as you can actually render, and preserve the returned order when inserting into the UI.
    • If unset, you’ll receive up to the placement’s configured maximum by default.

  • Customer Info (customer object) – This object can carry information about the end user or session, such as a user ID, demographics, or segments. Typical sub-fields might be: customer_id (your user’s unique ID), age, gender, city or region, device_type (e.g. Mobile vs Web), and any interest segments/tags. Business purpose: Customer data is used for advanced targeting and personalization. For example, if an advertiser’s campaign is targeting a specific audience (say, only users in Istanbul, or only users classified in a “tech enthusiast” segment), providing these attributes allows the ad server to include or exclude campaigns accordingly. Similarly, a customer.id improves attribution. session_id links events within a device/session, while a stable customer.id links events across sessions and devices; together they support end-to-end and cross-device sale attribution (e.g., ad viewed on web, purchase completed later in the app). Do not send disallowed PII; if derived from PII (e.g., email), hash/salt per your privacy policy and user consent. If omitted, ads are selected more generically and attribution remains session-scoped.

  • Region (region_id) – Indicates the user’s current region context (e.g., country/zone/city code used by your marketplace). Business purpose: Used for campaign eligibility. Only campaigns targeting the provided region_id are considered. If your marketplace is single-region, you can omit it.

  • Location (location_id) – Indicates the user’s current store / fulfillment location (e.g., a store code or warehouse code). Business purpose: Not a targeting key. When your product integration supports multi-location inventory, location_id lets the ad server prefer products in-stock for that specific location. This reduces the chance of showing ads for items unavailable at the user’s chosen store/fulfillment point. Provide location_id values that match the IDs in your product/inventory feed so stock lookups align. If your integration does not model multi-location stock, omit location_id.

  • Filters (filters) – Optional array of predefined tags from your product integration. It limits sponsored products to items that already carry the same tags in their integration payload (e.g., brand:Acme, in_stock:true, collection:ss25). Business purpose: align ad eligibility with your merchandising or compliance subsets without extra request-time logic. Tags are matched exactly—use the same key/value format you ingest during product sync.

    AND/OR semantics ([][]string):
    filters is evaluated as an array of filter groups, where each group contains one or more tag values. Inside a group, values are treated with OR; across groups, evaluation is AND. An ad is eligible when at least one tag in each group matches the product’s tags.

    Example:

    [
      ["color:red", "color:blue"], // Group 1 (OR)
      ["brand:apple", "brand:samsung"] // Group 2 (OR)
    ]

    The product must have (color:red OR color:blue) AND (brand:apple OR brand:samsung) among its tags to qualify.

    If multiple groups are provided, all groups must match; if no group matches, the response may be empty.

How Sponsored Product Ad Targeting Works​

When you send a Sponsored Product ad request with the above fields, GoWit will evaluate all eligible campaigns for that placement and context. The placement_id ensures only campaigns of type PRODUCT (i.e., ones that deliver product ads) tied to that slot are considered. Then the context fields (search keywords, category, etc.) are used to filter and score ads for relevance – for example, matching the ad’s targeting keywords to the user’s query. The system then selects the highest-ranking sponsored product(s) to return. The response for a Sponsored Product format will include the product_id of the item to display, the advertiser_id (so you know which seller’s product it is), and an ad_id (the unique identifier for that ad impression) among other data. You should use the product_id to fetch the product’s details from your own catalog (image, price, etc.) for rendering the ad – the ad unit is meant to look like a normal product listing, just with a sponsored label. (The GoWit platform doesn’t send down the entire product info in the ad response, only identifiers and perhaps a precomputed relevance score or tracking links, since it assumes the product is already known in your system.) Importantly, maintain the order of ads if more than one is returned. If you requested up to 2 ads, for example, and two come back, they are ranked – you should insert them into the page in the order given, at the predetermined positions, to honor the auction ranking. And if no ad is returned (HTTP 204 or empty list), simply leave the slot empty or collapse it gracefully (no ad to show, which will happen when there are no eligible bids or all campaigns hit pacing limits). Always handle this “no fill” case so that your page doesn’t show a blank gap or error.