Skip to main content

End-to-End Integration Flow: Sponsored Product Ads

Step-by-Step Walkthrough:​

  1. User visits a page – The user navigates to a search results, category listing, or homepage in the marketplace app or website. This triggers the page rendering flow on the partner’s side (e.g. user enters a query or opens a category page).

  2. Partner fetches organic results – The partner’s backend retrieves the normal organic product list for the page from its content/search service (e.g. an Algolia query or internal API). This provides the set of products the user would see organically for that context. For example, if the user searched "running shoes", the system gets the top N matching products to display.

  3. Prepare contextual ad request data – Once the organic results are obtained, the partner’s backend prepares a real-time ad request to GoWit. It gathers contextual information about the page and user session, including: the current placement ID for the ad slot, the list of visible product IDs on the page (from the organic results, typically with their categories), the page’s category or search query, and the session/customer identifiers. This context ensures GoWit can select ads relevant to what the user is browsing.

  4. Call GoWit’s /ads API (real-time) – The partner’s backend then immediately calls GoWit’s Sponsored Products ad endpoint (e.g. a POST request to /server/v2/ads) with the prepared context payload. This request is made server-to-server (keeping API keys and logic on the backend) and includes all the data from step 3 (placement_id, session_id, product IDs, category or search term, customer info, etc.). The ad request is timed very strictly – it is essentially made in parallel with preparing the rest of the page, and the partner’s system will not wait long for it (see timeout policy below).

  5. GoWit returns a ranked ad list (or no ads) – GoWit’s ad server processes the request by evaluating eligible campaigns for the given placement and context. It then responds with either an HTTP 200 and a list of sponsored product ads, or HTTP 204 No Content if no ad meets the criteria or budget at that moment. The response contains the essential data for each ad: notably a product_id, an advertiser_id (seller), and a unique ad_id for tracking, and possibly a recommended position or metadata (e.g. an image URL or redirect URL for click tracking). No full product details (name, price, image) are sent in this payload – just the identifiers and ad-specific info. (If no ads are eligible, the 204 response indicates “no fill,” meaning the page should continue with organic content only.)

  6. Partner enriches and inserts sponsored product(s) – If a sponsored ad is returned, the partner’s backend takes each ad’s product_id and looks up the product’s details in its own product catalog/database. This yields the product’s title, image, price, etc., which were not included in the ad response. The partner then inserts the sponsored product(s) into the organic results feed or designated ad slots on the page. The ads are injected at predetermined positions (e.g. a specific slot in the search results) and in the exact order the GoWit API provided. The ad items are formatted to appear as native product listings (same template as an organic item), but with a clear “Sponsored” label or indication to comply with UX/legal requirements. (GoWit provides the data and ranking; rendering the ad in the UI is the partner’s responsibility – the ad should blend in look-and-feel with organic content aside from the sponsorship disclosure.)

  7. Fallback for no ads or timeout – If the ad request returns no ads (empty list or 204 response) or if it times out (takes too long), the partner simply continues to render the page with organic results only. The ad slot is left empty or collapsed gracefully – the user will just see the normal product list with no sponsored items in that case. The backend should not delay page rendering waiting for ads beyond the set timeout. It also should not retry the ad request on that page load. In summary, whenever the ad service doesn’t respond in time or has no content, the page proceeds as an organic-only page (this ensures reliability and no broken blanks in the UI). The front-end then receives the combined result set (organic plus any ads) from the backend and presents the page to the user.

Example: Pseudocode for Ad Request with Timeout and Fallback (server-side logic)​

# Define a strict timeout (e.g., 100ms)
AD_REQUEST_TIMEOUT_MS = 100  

# Prepare the ad request payload (placement, session, product IDs, etc.)
payload = {
    "marketplace_id": MARKETPLACE_ID,
    "placement_id": PLACEMENT_ID,
    "session_id": SESSION_ID,
    # ... other context: products list, category or search term, customer info ...
}

sponsored_ads = []  # to store any returned ads
try:
    # Call GoWit's ads API (HTTP POST) with a timeout
    response = http_post(GOWIT_ADS_ENDPOINT, json=payload, timeout=AD_REQUEST_TIMEOUT_MS)
    # If the request returns within 100ms, process the response
    if response.status_code == 200:
        sponsored_ads = response.json().get("ads", [])  # list of ads (if any)
    # A 204 No Content or an empty ads list will result in sponsored_ads remaining empty
except TimeoutError:
    # If the request doesn't return within 100ms, we treat it as a timeout
    # (sponsored_ads stays empty)
    pass

# === Post-processing: enrich and merge ads ===
if sponsored_ads:
    for ad in sponsored_ads:
        prod_id = ad["product_id"]
        # Lookup product details from partner's catalog
        product = get_product_by_id(prod_id)  
        ad["title"] = product.title
        ad["price"] = product.price
        ad["image"] = product.image_url
        # (Add any “sponsored” flag for frontend if needed)
    # Merge sponsored_ads into the organic results list at the appropriate slot(s)
    final_results = insert_ads_into_results(organic_results, sponsored_ads)
else:
    # No ads to show (timeout or empty response); use organic results as-is
    final_results = organic_results

# Return final_results to the front-end for rendering (ads will be labeled as sponsored in UI)

Ad Timeout & No-Ads Fallback Policy​

In any integration of GoWit ads, the partner must implement a strict timeout and graceful fallback for ad requests. If the ad API call does not return within ~100 ms, or if it returns with no ads, the page should be rendered without any ads (only the organic content). The partner’s system should never hold up the user’s page waiting indefinitely for ads, and no retry attempts should be made on that page load – treat it as a “no ad” case and move on. This ensures that a slow or empty ad response will not degrade the user experience. This timeout-and-fallback mechanism applies equally to web and mobile app implementations – both follow the same server-side API call pattern and must abide by the same timeout limits and no-retry policy. The result is that whether the user is on a website or in an app, they either see relevant sponsored products injected in the page if the ads return in time, or the page simply shows the normal organic results if not, with no broken slots.

Ad Response Caching Policy (Mandatory)​

Do not cache responses from the GoWit /ads endpoint at any layer (browser, app, CDN, reverse proxy, or server memory). Sponsored product eligibility and ranking are real-time and depend on per-request context (placement, session/customer, visible products, region/location) and dynamic campaign state (budget/pacing). Reusing an old response can surface ineligible products, misreport spend, and break attribution.

Sample Ad Request Payloads​

Below are example ad request payloads for different scenarios. These illustrate how to populate the JSON request with the required and optional fields for Sponsored Product Ads. In each case, the request is made to the GoWit Ads API endpoint (e.g. POST https://<your-environment>.gowit.com/server/v2/ads) with an authorization header containing your API key.

Note: These examples assume a single placement is requested at a time (common case). Your actual marketplace_id and placement_id values will be provided by GoWit. The session_id should be a unique string per user session. Replace example IDs with real IDs from your system.

Example 1: Search Results Page Ad Request​

When a user performs a search on your marketplace, you should send an ad request including the search query and the list of products the user is seeing in the organic results. This provides context so the ad can be matched to the query and avoids duplicating products already shown. For instance, on a search results page for “wireless headphones” showing a list of products, an ad request payload might look like:

{
    "marketplace_id": 42,
    "placements": [
        {
            "placement_id": 101,
            "max_ads": 2
        }
    ],
    "session_id": "abc123-456-def789-0001",
    "page_number": 0,
    "search": "wireless headphones",
    "products": [
        {
            "id": "SKU-111",
            "category": "Electronics > Headphones"
        },
        {
            "id": "SKU-112",
            "category": "Electronics > Headphones"
        },
        {
            "id": "SKU-113",
            "category": "Electronics > Headphones"
        }
    ]
}

Explanation​

Here we include the search term "wireless headphones" and the top organic products (with their categories) currently shown to the user.
page_number: 0 indicates this is the first page of results.
We set "max_ads": 2 to ask for at most two sponsored products (even if the placement could allow more).
The session_id uniquely identifies the user’s browsing session, allowing GoWit to track this impression and any subsequent actions.
The ad server will use the search keyword and the categories of the visible products to select relevant sponsored items (e.g., headphone products) to return.

Example 2: Category Page Ad Request​

On a category or listing page (for example, the user navigated to Electronics > Mobile Phones), you should provide the category context and the list of visible products on that page. This helps the ad server return a product ad relevant to that category. Example payload for a category page (Electronics > Mobile Phones category, first page of products):

{
    "marketplace_id": 42,
    "placements": [
        {
            "placement_id": 202
        }
    ],
    "session_id": "abc123-456-def789-0001",
    "page_number": 0,
    "category": "Electronics > Mobile Phones",
    "products": [
        {
            "id": "SKU-2001",
            "category": "Electronics > Mobile Phones"
        },
        {
            "id": "SKU-2002",
            "category": "Electronics > Mobile Phones"
        },
        {
            "id": "SKU-2003",
            "category": "Electronics > Mobile Phones"
        }
    ]
}

Explanation​

We provide the category path the user is browsing, along with the product IDs and categories of the items currently shown on that page. This tells GoWit that the context is Mobile Phones and shows which phones are already on the page. The ad server will likely return a sponsored product from the relevant categories (assuming campaigns are targeting it). In this example we didn’t set max_ads, so the default for that placement will apply (e.g., if placement 202 is configured to return up to 1 ad, it will return at most one). We also didn’t include a search term since this is a category navigation, not a search results page.

Example 3: Homepage Ad Request (No Contextual Signals)​

On the homepage (or any non-search, non-category landing page), there may be an ad slot for a sponsored product even though the user hasn’t provided any explicit context (no search query or specific category view). In this case, you will omit the contextual fields and just identify the placement and user session (and any applicable targeting info like location or customer segments). Example payload for a homepage ad slot request:

{
    "marketplace_id": 42,
    "placements": [
        {
            "placement_id": 303
        }
    ],
    "session_id": "abc123-456-def789-0001"
}

Explanation​

In this minimalist request, we only send the required identifiers: the marketplace, the placement (e.g., a homepage placement ID), and the session ID. We do not include search, category, or products because on a generic homepage there are no specific query or category signals. We also omit page_number since the homepage isn’t paginated (and as noted, page_number is only for paged lists). With no contextual filters provided, the ad server will choose a sponsored product ad based on broader targeting rules – for example, a top-performing campaign or a product with wide appeal. You could include optional fields here if available: for instance, if your site knows the user’s region or has some personalization segments, you might pass "region_id" or a "customer" profile to help select an appropriate ad.

These examples demonstrate how to form the ad request JSON in various scenarios. Always ensure you include the session_id and correct placement_id, and provide as much context as possible (search term, category, product list) for relevance. The response from GoWit will correspond to what you request – for each placement you ask for, you’ll get a placement result in the response containing sponsored ads (see next section).

Ad Response Handling​

When you call the Ads API with a Sponsored Product ad request, the GoWit ad server will return a JSON response containing the selected ad(s) and related info. Understanding this response is crucial for rendering the ads correctly and handling cases where no ad is returned.

Expected response structure​

The response will typically include the placement ID and an array of ads for that placement. Each ad entry will contain at minimum:

  • ad_id – A unique UUID for this ad impression. This ID ties together the impression and any subsequent click or conversion events. You should keep track of it (e.g. send it to the frontend, so if the user clicks the ad, you can later report that click with this ad_id). It’s also used by GoWit for attribution (to know which ad was seen).
  • product_id – The ID of the product to display as an ad. Use it to fetch the product’s details (product’s title, image, price, etc.) from your product catalog or database.
  • advertiser_id – The ID of the advertiser (seller) who is promoting that product. This corresponds to the IDs in your advertiser (seller) feed.
  • position – The position rank of this ad in the returned list. If you only get one ad, it will usually have "position": 1. If you requested multiple (max_ads > 1), the ads may have positions 1, 2, etc., indicating the order they should be considered.
{
  "placements": [
    {
      "placement_id": 101,
      "ads": [
        {
          "ad_id": "8bf7ad1f-a4ae-4854-8dc7-652ec0bbdd64",
          "product_id": "SKU-112",
          "advertiser_id": "SELLER-45",
          "position": 1
        }
      ]
    }
  ],
  "response_id": "e38d2174-c088-4b70-b5c7-1e3f03e1a57b"
}

Using the ad response data​

Your integration should take the returned product_id and use it to fetch the product’s details from your own system (e.g., get the product name, image, price from your product catalog service or cache) The Sponsored Product ad is meant to look like a native product listing, so you render it using your site’s product tile template, populated with this product’s info, plus a “Sponsored” label. Note: The GoWit response does not include the full product details (to avoid duplication and because it assumes you have the product data already). It just gives you identifiers. You should also note the advertiser_id (the seller or vendor of that product) in case you need it for click-through handling or reporting. The ad_id must be retained for event tracking (impressions, clicks).

Rendering and order​

Always insert the sponsored product ad into the page in the exact order provided by the response ranking. If you requested up to 2 ads and the response gives you two, they will be in ranked order – e.g., the first ad is the higher-ranked one. Place them in the predetermined slots (for instance, if you intended to show one ad after every 5 organic items, put them accordingly). Preserving the order and position is important to honor the auction results and comply with how the ads were meant to appear. Also, ensure you label the ad as sponsored in the UI per advertising disclosure standards.

Handling no-ad cases:​

It is common (and expected) that sometimes the ad server will return no ads for a request. This can happen if no campaign meets the targeting criteria, if all eligible ads have been exhausted or paced out, or if there was some filtering (like your filters or category) that left no matches. In such cases, the API may return an HTTP 204 No Content, or a 200 with an empty ads list. Your code should handle this gracefully. Fail silently when no ad is returned: do not display an empty container or an error – simply do nothing or collapse the ad slot so that the page doesn’t show a blank gap. Similarly, if the ad request itself fails (e.g. network error or API returns an error code), catch that error and treat it as “no ad” for that page load. The page should continue to function normally even if an ad is absent or cannot be fetched. It’s a good practice to implement a short timeout on ad requests (so your page isn’t held up if the ad server is slow) and to fallback to showing nothing if the timeout is exceeded.

Fallback behavior:​

In some layouts, you might choose to have a fallback content if no ad comes back (for example, a house ad or a placeholder). This is optional and up to your design. The key is that a missing ad should not break the user experience. During testing, be sure to verify that when the ad API returns no content, your front-end cleanly skips showing an ad slot. GoWit recommends simply collapsing the space or filling it with organic content to avoid layout jitter.

In summary, use product_id and advertiser_id from the ad response to display the sponsored product using your own product data, maintain the order of any ads, and handle empty results by failing gracefully (no errors or empty components)