Skip to main content
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: targeting elements used to fetch the campaigns that target a given impression opportunity. Triggers are configured on campaign creation.
    • 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.
  • Attribute filter: Unlike triggers, attribute filters are mechanism for the API client (the marketplace) to exclude specific products that don’t match specific catalog properties. So even though a campaign might be interested in the impression opportunity (the triggers match), the marketplace blocks that bid because it doesn’t fit specific product attributes. See Filtering auctions by attributes.

​
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. If the request includes an attribute filter, non-matching ads are excluded at this stage, before any ranking or pricing happens. 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.