Skip to content
Toposort Logo
ad-server

Auctions API

Topsort’s Auctions API determines which bids from active campaigns should be promoted. As a marketplace admin, you can define where, when and how auctions should be created. We have three types of auctions available:

  • Sponsored Products: allow promoting specific products in search results, category listings, PDPs and product carousels.
  • Banner Ads and Video Ads: ads to be displayed in search, category or landing pages.
  • Sponsored Brands: allow promoting brands in search, category or landing pages.

An auction should be created for each page view. If the auction results are cached, the same results could be shown to multiple users or to the same user multiple times. This will impact campaign performance tracking.

Auction Creation

Use the appropriate API to create an auction and retrieve winners. The key parameters needed for any auction are:

  • Type: listings, banners, videos or brands
  • Max winners: maximum number of winners to be returned. If the auction engine encounters less winners then the maximum number requested, all winners will be returned.
  • Triggers: triggers are targeting elements used to filter which campaigns are eligible in the auction.
    • Product IDs - Automatic Trigger: Targets bids for specific products. This trigger can be used to promote products that were returned by your search engine and have bids from active campaigns.
    • Category IDs: Targets bids for specific categories. This trigger can be used to return winners related to one or more categories.
    • Search Query: Target bids matching keywords.
    • Geolocation: Target bids matching geolocation.

Auction Resolution

Topsort matches the auction criteria with active campaigns and filters bids that are eligible to participate, considering the parameters defined in the auction request, and are above the reserve price. Reserve price is the minimum bid price allowed by the marketplace.

Winning bids are defined and ranked, considering two main objectives:

  • Optimize advertiser ROAS, considering the best products based on their metrics (CTR, CVR, quality score).
  • Maximize retailers revenue, considering the bidding amount of each product.

Displaying Winners and Tracking Events

Winning bids are returned by Topsort’s API with an unique Resolved Bid ID. This parameter identifies every promoted item that participated in an auction. It’s used to ensure accurate reporting and attribution. This parameter should be sent with the impressions, clicks and purchases that are reported with the Events API.