Lupa Ads

What is Lupa Ads?

Lupa Ads is a new tool that lets advertisers create and manage ads that are natively integrated into search results, recommendations and product catalogs.

If you are already using LupaSearch in your Search Results, enabling Lupa Ads requires minimal effort: there are no new indices to build, no separate APIs to integrate, and no extra search calls to make. Sponsored results are returned through the same LupaSearch endpoints you already use — the only change on your side is a small frontend tweak to render them.

If you are not yet using LupaSearch for your search, recommendations or product catalog, you can still adopt Lupa Ads on its own. The LupaSearch API can be called purely as an ads source — returning sponsored items (or just their ids) together with their suggested placements — which you then merge into your existing search results, recommendations or catalog listings.

How to enable Lupa Ads for my organization?

Lupa Ads is available on request. Contact us at [email protected] and we will enable Lupa Ads for your organization. Once enabled, you can start creating and managing your stores, advertisers and campaigns from the Lupa Ads console.

Lupa Ads in search results

What is needed for integration?

If you are already using LupaSearch in your Search Results, integration is essentially effortless:

Lupa Ads reuses your existing search indices — no additional data ingestion is required.
Top keywords and campaign targeting are derived automatically from your LupaSearch analytics.
Sponsored items are returned inline in the normal search response, so no extra API calls are needed.

The only change on your side is to detect the _boosted flag in search results and display sponsored items according to your design (for example, with a "Sponsored" label).

How sponsored results appear in the response

When at least one campaign from one of your advertisers is active, matching search results will include a _boosted: true field.

Example request:

{
  "searchText": "toys"
}

Example response:

{
  "searchText": "toys",
  "total": 3,
  "items": [
    {
      "name": "Toy Car",
      "id": "1",
      "_boosted": true
    },
    {
      "name": "Toy Car Basic",
      "id": "2"
    },
    {
      "name": "Best Car",
      "id": "5",
      "_boosted": true
    }
  ]
}

Use the _boosted field on the frontend to identify which results are sponsored and render them accordingly.

Relevance and placement

LupaSearch ensures that boosted/sponsored results remain relevant to the search query — irrelevant products are never promoted.
Boosted products can appear anywhere in the result list. Their allowed positions are controlled in your organization settings.

Ads tracking

Lupa Ads does not need a separate tracking API. Impressions are recorded by LupaSearch when it serves a search request, while clicks and purchases are taken from the events you already send to the Events API. These events are used for campaign reports and for charging advertisers.

Ad event	Recorded from	Charged to advertiser
Impression	Search request that returns a sponsored item on the requested page	Yes, per impression (CPM)
Click	`itemClick` or `addToCart` event	Yes, per click (CPC)
Purchase	`purchasedItems` event	No, used for reports

Impressions

An impression is recorded for each sponsored item returned on the requested results page, so no impression event needs to be sent. Include sessionId and userId in the search request:

{
  "searchText": "running shoes",
  "limit": 24,
  "sessionId": "x-session-id-1",
  "userId": "x-user-id-1"
}

Impressions are only recorded for requests with a non-empty searchText.
An impression is counted when the page is served, not when the item becomes visible. Do not prefetch results pages the user may never open, and do not request more items than you display.
Render sponsored items in the positions returned by the API. Do not remove or reorder them on the frontend.

Clicks

Send an itemClick event when a user opens a product from the search results, and an addToCart event when a product is added to the cart from the results page:

{
  "queryKey": "ax2q422v8f7z",
  "name": "itemClick",
  "searchQuery": "running shoes",
  "itemId": "25535",
  "sessionId": "x-session-id-1",
  "userId": "x-user-id-1"
}

searchQuery must be exactly the searchText of the search that returned the item. Clicks are matched to campaigns by product id and the campaign keyword, so a different value may match no campaign or the wrong one.
Both itemClick and addToCart are counted as ad clicks. Send searchQuery with addToCart only when the product is added from the search results, so a single visit is not counted twice.
Clicks from recommendation queries are not counted as ad clicks.
Send each click once. Repeated clicks on the same campaign by the same visitor are limited per day.

Purchases

Send a purchasedItems event after an order is placed. It uses the search index id (indexId) instead of a query key:

{
  "name": "purchasedItems",
  "indexId": "6f1d2c7e-0b4a-4c1e-9a55-2b3c4d5e6f70",
  "transactionId": "order-100231",
  "items": [{ "itemId": "25535", "qty": 2, "price": 15.5, "currency": "EUR" }],
  "sessionId": "x-session-id-1",
  "userId": "x-user-id-1"
}

price is the price of a single unit, not the line total.
Send one event per order with a unique transactionId.
A purchased product is attributed to an active campaign that promotes it. Purchases are used for revenue reports only and are not charged.

Visitor identification

Keep sessionId the same for the whole visit and userId the same across visits. Use anonymous ids, never emails or names.
Use the same sessionId and userId in search requests and events, so impressions, clicks and purchases can be linked in reports.
Visitors are identified by IP address first. Send search requests and events from the browser, or forward the user's IP if requests go through your server. Otherwise all users appear as a single visitor and their impressions and clicks are limited together.

Troubleshooting

Symptom	Likely cause
No sponsored items in results	No active campaign keyword matches the search text, or the campaign reached its daily budget
Clicks are not counted	`searchQuery` differs from the search text, or the daily click limit for the visitor was reached
Purchases missing in campaign reports	`indexId` is not the index used by the store, or the product is not in an active campaign
Campaign paused automatically	Advertiser's wallet balance or total campaign budget was used up

Ad reports are not updated in real time. Events are processed in batches, so new data may take some time to appear.

Lupa Ads in recommendations

This functionality is currently in development and will be released in the near future. For any questions, contact us at [email protected].

Lupa Ads in product catalog

This functionality is currently in development and will be released in the near future. For any questions, contact us at [email protected].

Lupa Ads banners

This functionality is currently in development and will be released in the near future. For any questions, contact us at [email protected].