Ad Server API for Retail Media and Marketplaces | Topsort
An ad server API is a programmatic interface that lets commerce platforms request ad decisions, run real-time auctions, return sponsored results, and track conversion events — all without surrendering control over the user experience.
Topsort provides an ad server API built specifically for marketplaces, retailers, delivery apps, and travel platforms that need to launch retail media infrastructure natively inside their own product. If your team needs to integrate sponsored listings, run auctions, or connect ad serving to catalog, search, and checkout — this page explains what that looks like in practice.
What Is an Ad Server API?
An ad server API is a set of structured REST endpoints that allows an application to request and receive ad decisions programmatically. Rather than relying on a fixed ad placement template or a third-party iframe, an API-first model lets your engineering team embed ad serving directly into any surface: search results, category pages, home feeds, checkout flows, or recommendation engines.
How a typical ad server API request cycle works:
- Your system sends placement context — search query, eligible product IDs, session ID, marketplace ID.
- The ad server evaluates eligible campaigns against targeting rules and budget constraints.
- Auction or ranking logic runs in real time, typically in under 50ms.
- The API returns the winning sponsored result: product ID, ad type, auction ID, and rank.
- Your frontend renders the result natively within your existing UI.
- Your system fires impression, click, add-to-cart, and purchase events back for closed-loop attribution.
The key difference between an ad server API and a traditional ad platform: your team controls the render layer. The API handles the auction. You own the experience.
Why Retail Media Requires an API-First Ad Server
Most general-purpose ad servers were not designed for commerce. The core problem is that ad servers were built for publishers — and commerce requires fundamentally different infrastructure: the auction must understand catalog, inventory, and purchase context that has nothing to do with page URLs or browser cookies.
A retail media ad server API needs to process:
- Search query — what the shopper is actively looking for
- Product candidates — the specific SKUs eligible for a given placement
- Category and subcategory context — to match ads to browse intent
- Inventory and availability — to avoid serving ads for out-of-stock items
- Seller and vendor eligibility — who is allowed to bid for a placement
- User or session signals — behavioral and contextual data for relevance
- Campaign budget and pacing — to distribute spend accurately
- Bid data — CPCs, CPMs, or vCPMs depending on auction type
- Attribution events — impressions, clicks, add-to-carts, purchases, returns
Because every commerce platform has its own data model, catalog structure, and user experience, an API-first architecture is the only way to integrate monetization without rebuilding it around someone else's schema. This is why teams across marketplaces, retailers, delivery apps, and travel platforms choose API-native infrastructure over traditional ad platforms, like Topsort’s T-Engine.
What a Retail Media Ad Server API Should Support
Real-Time Auction Requests
Send placement type, search query, eligible SKUs, seller context, and session data to trigger an ad decision. The API should return a ranked result in milliseconds, with full auction metadata so your team can audit and optimize.
Sponsored Listings and Sponsored Display
Return winning sponsored listings for search and category placements, as well as sponsored brands, display banners, native placements, and video ads for home feed, brand pages, or offsite surfaces. A strong ad server API handles all formats from a unified auction layer.
Event Tracking and Attribution
Fire impression, click, add-to-cart, and purchase events back to the ad server so campaign reporting stays accurate and attribution is tied to real commerce outcomes — not just clicks. More sophisticated implementations support per-format attribution measurement so you can understand which ad types drive incremental sales vs. assisted conversions.
Campaign Management Workflows
Support programmatic campaign creation, budget setting, targeting rules, pacing controls, and bid adjustments via API — so sellers and advertisers can manage campaigns without requiring manual ad ops intervention.
Catalog and Inventory Integration
Connect ad decisions to your live product catalog, inventory status, and seller data. This prevents serving ads for unavailable products and enables relevance-based ranking that considers both bid and product quality.
Reporting and Analytics API
Expose ROAS, CTR, spend, impressions, and conversion data to internal dashboards, advertiser portals, and BI tools. The best implementations make it possible to query retail media performance data in natural language rather than requiring custom BI queries for every report.
Demand Mediation and Programmatic Fill
Maximize yield by filling unsold inventory with programmatic demand sources alongside your direct auction. Without mediation, unsold placements generate zero revenue — filling every slot is one of the highest-leverage yield improvements a retail media platform can make.
Webhooks and Automation
Trigger automated workflows based on campaign status changes, budget thresholds, billing events, or performance anomalies — without polling the API continuously.
Example: Ad Server API Request and Response
Here is what a real auction request from a marketplace search page looks like using Topsort's ad server API. Full technical reference is available on our Developer Portal.
Request — sponsored listing auction on a search results page:
{
"auctions": [
{
"type": "listings",
"slots": 2,
"products": {
"ids": ["sku_123", "sku_456", "sku_789"]
},
"context": {
"page": "search",
"searchQuery": "running shoes"
}
}
],
"session": {
"sessionId": "abc_123",
"consumerId": "user_456"
}
}
Response — winning sponsored results:
{
"results": [
{
"resultType": "listings",
"winners": [
{
"rank": 1,
"type": "product",
"id": "sku_456",
"resolvedBidId": "auc_789"
}
]
}
]
}
The marketplace renders sku_456 as a sponsored listing in rank 1, then fires an impression event against auc_789. When the shopper clicks and purchases, a purchase event closes the attribution loop. For teams running into friction during integration, it's worth reviewing the most common ad server platform errors that hurt performance.
Ad Server API vs. Traditional Ad Platform: Key Differences
Ad Server APITraditional Ad PlatformIntegration modelEmbedded via REST API into your own productTag-based or iframe, third-party renderRender controlYour frontend, your design systemPlatform-defined templatesAuction customizationConfigurable ranking, targeting, bid logicFixed auction rulesCommerce data supportNative: catalog, inventory, search, checkoutLimited or requires custom workaroundsTime to launchWeeks with API-first infrastructureMonths with custom developmentAdvertiser experienceWhite-labeled, self-serve, native to your productGeneric dashboards or external portals
Why Teams Choose Topsort's Ad Server API
Topsort's ad server API is purpose-built for commerce monetization — not a general-purpose ad server with a retail media add-on. It was designed from the ground up for platforms that need to run sponsored listings, display, native ads, and more ad formats.
What Topsort's ad server API enables:
- Launch sponsored listings and sponsored display from a single auction infrastructure
- Run real-time first-price or second-price auctions with configurable ranking signals powered by T-Engine
- Connect ad decisions directly to your live product catalog and inventory with Data Genie
- Track impressions, clicks, add-to-carts, and purchases for closed-loop attribution
- Give sellers and advertisers a white-labeled self-serve campaign management experience
- Optimize bid and relevance performance automatically with T-Brain and Toptimize
- Fill every ad slot with programmatic demand through Toptimize SSP
- Go live in weeks with T-Zero, Topsort's zero-downtime migration infrastructure
Teams across the world have launched retail media on Topsort's API — from Carousell across Southeast Asia to Despegar's travel media business to RD Saúde, Brazil's largest pharmacy network. Whether you're launching, scaling, optimizing, or expanding your retail media program, Topsort provides the infrastructure to do it without building every component internally.
Summary: When to Use an Ad Server API
An ad server API is the right choice when:
- You operate a marketplace, retailer, delivery app, or commerce platform
- You need ad serving to integrate with your own catalog, search, and checkout data
- You want to control the render layer and keep the shopping experience native
- You are launching sponsored listings, sponsored display, or a self-serve advertiser portal
- You need closed-loop attribution tied to actual purchase events — not just clicks
For a deeper look at how retail media infrastructure has evolved, the shift from ad servers to agent infrastructure is worth reading before you evaluate any platform.
Frequently Asked Questions
What is an ad server API?
An ad server API is a programmatic interface that allows an application to request and receive ad decisions from an ad serving system. It lets engineering teams embed ad serving — including auctions, sponsored results, and event tracking — directly into any surface of their product, rather than relying on third-party tags or iframes. The API handles auction logic and returns winning ads; the publisher or marketplace controls how those ads are rendered.
How does an ad server API work?
An ad server API works by accepting a request that contains placement context — such as search query, eligible products, session data, and placement type — then running an auction or ranking algorithm and returning the winning ad or sponsored result. The calling system then renders the result and fires event callbacks (impression, click, purchase) back to the API for attribution and reporting. Full technical documentation is available at docs.topsort.com.
What is the difference between an ad server API and a traditional ad server?
A traditional ad server typically uses JavaScript tags, iframes, or SDKs to serve and render ads through a third-party system. An ad server API puts your engineering team in control: you send a request, receive a structured response, and render the ad within your own UI. This model gives commerce platforms significantly more flexibility over auction logic, targeting rules, and the end-user experience than tag-based ad serving allows.
Why does retail media need an API-first ad server?
Retail media ad serving requires access to commerce data — live product catalog, inventory status, search queries, seller eligibility, and real purchase events — that traditional ad servers were not built to consume. An API-first retail media ad server can natively accept this data in each auction request, run relevance-aware auctions, and return results tied to actual commerce context rather than page-level signals.
Can an ad server API support sponsored products and sponsored listings?
Yes. A retail media ad server API can return sponsored product results for search and category placements, sponsored brand placements for home and collection pages, and sponsored display results for native ad surfaces. A well-designed API handles all of these formats from a unified auction layer, with each format accessible via the same core request structure.
What events should be tracked with an ad server API?
At minimum, an ad server API should track impressions (when an ad is rendered), clicks (when a user engages), and purchases (when a conversion attributed to an ad is completed). More complete implementations also track add-to-cart events, view-through conversions, and return events — all of which feed into ROAS reporting and campaign optimization.
Does Topsort offer an ad server API for retail media?
Yes. Topsort provides an ad server API purpose-built for retail media and marketplace monetization. It supports real-time auctions, sponsored listings, display ads, event tracking, closed-loop attribution, and a white-labeled self-serve advertiser experience — all accessible via REST API and documented at docs.topsort.com.
How long does it take to integrate an ad server API?
With Topsort's ad server API, most marketplace and retail media teams can complete a basic integration — including auction requests, sponsored listing responses, and event tracking — in a few weeks. Topsort's infrastructure is specifically designed for zero-downtime, zero-data-loss onboarding, which means you don't have to choose between moving fast and protecting existing data. Full integrations including advertiser self-serve, reporting dashboards, and catalog sync typically take four to eight weeks.
What is the difference between an ad server API and a DSP?
An ad server API is used by publishers, marketplaces, and retailers to manage the supply side — deciding which ads to show, running auctions, and tracking outcomes on their own inventory. A DSP (demand-side platform) is used by advertisers to buy ad placements across multiple publishers. Topsort's ad server API operates on the supply side, helping commerce platforms build and monetize their own retail media inventory.
How does AI improve an ad server API for retail media?
AI improves retail media ad serving by optimizing auction ranking, bid pacing, relevance scoring, and budget allocation in real time — beyond what static rules can achieve. The best implementations apply machine learning to improve yield for the platform and ROAS for advertisers simultaneously, as explored in how AI is transforming retail ad auctions.
Next Recommended Article
See how Topsort's ad server API works — and how fast your team can launch →