(R.id.bannerView)
val bannerConfig = BannerConfig.CategorySingle(slotId = "slot", category = "category")
bannerView.setup(
bannerConfig = bannerConfig,
screenName = "sample_activity",
onClick = { id, entityType -> onBannerClick(id, entityType) }
)
}
}
}
```
For full documentation, see the [GitHub repository](https://github.com/Topsort/topsort.kt).
# iOS
Source: https://docs.topsort.com/en/ad-platform/sdks/ios
Integrate Topsort's Swift library for auction requests and event tracking in mobile applications
Topsort's [Swift library](https://github.com/Topsort/topsort.swift) enables our clients to easily send auction requests and track events within iOS applications.
## Installation
Install using package.swift:
```swift theme={null}
let package = Package(
dependencies: [
.package(url: "https://github.com/Topsort/topsort.swift.git", from: "1.0.0"),
]
)
```
## Configuration
```swift theme={null}
import SwiftUI
import Topsort
@main
struct MyApp: App {
init() {
Topsort.shared.configure(apiKey: "your-api-key", url: "https://api.topsort.com")
}
var body: some Scene {
WindowGroup {
ContentView()
}
}
}
```
## Requesting Auctions
```swift theme={null}
import Topsort
let products = AuctionProducts(ids: ["p_dsad", "p_dvra", "p_oplf"])
let category = AuctionCategory(id: "c_fdfa")
let auctions = [
Auction(type: "banners", slots: 1, slotId: "home-banner", device: "mobile", category: category),
Auction(type: "listings", slots: 2, device: "mobile", products: products)
]
let result: AuctionResponse = await Topsort.shared.executeAuctions(auctions: auctions)
```
## Reporting Events
### Impressions and Clicks
```swift theme={null}
var body: some View {
VStack {
AsyncImage(url: self.product.image_url)
Text(self.product.name)
}
.onAppear {
Topsort.shared.track(impression: self.event())
}
.onTapGesture {
Topsort.shared.track(click: self.event())
}
}
```
### Purchases
```swift theme={null}
Button("Purchase me!") {
let item = PurchaseItem(productId: myProduct.id, unitPrice: myProduct.price)
let event = PurchaseEvent(items: [item], occurredAt: Date.now)
Topsort.shared.track(purchase: event)
}
```
## Displaying Banners
```swift theme={null}
import TopsortBanners
struct ContentView: View {
var body: some View {
TopsortBanner(bannerAuctionBuilder: .init(slotId: "slotId", deviceType: "device"))
.contentMode(.fill)
.onNoWinners({ })
.onError({ error in })
.onImageLoad({ })
.buttonClickedAction({ response in })
.frame(maxHeight: 50)
.clipped()
}
}
```
For full documentation, see the [GitHub repository](https://github.com/Topsort/topsort.swift).
# JavaScript SDK
Source: https://docs.topsort.com/en/ad-platform/sdks/javascript-sdk
Overview of Topsort's JavaScript SDK for auctions and event tracking
The [Topsort JavaScript SDK](https://github.com/Topsort/topsort.js) is the official client library to integrate with Topsort's auction and event tracking APIs. Built in TypeScript, this SDK simplifies the integration, allowing the creation of an end-to-end flow in minutes.
## Installation
```html theme={null}
```
## Creating an Auction
```javascript theme={null}
import { TopsortClient } from "https://unpkg.com/@topsort/sdk@latest/dist/index.mjs";
const topsortClient = new TopsortClient({ apiKey: window.TS.token });
const auctionDetails = {
auctions: [
{
type: "listings",
slots: 3,
searchQuery: "winter",
},
{
type: "banners",
slots: 1,
device: "desktop",
slotId: "slot123",
},
],
};
topsortClient
.createAuction(auctionDetails)
.then((result) => console.log("Auction Result", result))
.catch((error) => console.error("Auction Error", error));
```
## Reporting Events
```javascript theme={null}
const winners = auctionResult.results.flatMap((result) => result.winners || []);
if (winners.length > 0) {
const impressions = winners.map((winner) => ({
resolvedBidId: winner.resolvedBidId,
id: crypto.randomUUID(),
occurredAt: new Date().toISOString(),
opaqueUserId: crypto.randomUUID(),
placement: { path: "/search/winter" },
}));
topsortClient
.reportEvent({ impressions })
.then((result) => console.log("Event Result", result))
.catch((error) => console.error("Event Error", error));
}
```
## Retryable Errors
The `reportEvent` function returns `retry: true` for 429 or 5xx errors:
```javascript theme={null}
topsortClient.reportEvent(eventPayload).then((result) => {
if (result.retry) {
console.warn("Transient error. Retry the call.");
}
});
```
For full documentation and end-to-end examples, see the [GitHub repository](https://github.com/Topsort/topsort.js).
# Topsort.php
Source: https://docs.topsort.com/en/ad-platform/sdks/topsort-php
A PHP Software Development Kit for interacting with the auctions and events endpoints
[Topsort.php](https://github.com/Topsort/topsort.php) is a PHP Software Development Kit for Topsort Promoted Listings API.
## Installation
Install with Composer:
```bash theme={null}
composer require topsort/sdk
```
Or add to your composer.json:
```json theme={null}
{
"require": {
"topsort/sdk": "3.0.0"
}
}
```
## Running an Auction
```php theme={null}
create_auction($slots, $products)->wait();
```
## Reporting Click Events
```php theme={null}
"/categories/shoes",
];
$topsort_client->report_click([
"placement" => $placement,
"resolvedBidId" => "AKFU78",
]);
```
## Reporting Impression Events
```php theme={null}
[
"path" => "/categories/shoes",
],
"resolvedBidId" => "AKFU78",
];
$topsort_client->report_impression($impression);
```
## Reporting Purchase Events
```php theme={null}
"gDG0HV97ed2s",
"quantity" => 2,
"unitPrice" => 10000,
]
];
$topsort_client->report_purchase([
"occurredAt" => new DateTime(),
"items" => $items,
]);
```
For full documentation, see the [GitHub repository](https://github.com/Topsort/topsort.php).
# Assets API
Source: https://docs.topsort.com/en/ad-server/additional-apis/assets-api
Integrate with our Assets API
Topsort's [Assets API](/en/api-reference/assets-api) is designed to provide tools for managing assets that can be used in campaigns (e.g. banner ads). It also includes collection management tools. These are its main functionalities:
* Create, retrieve, update, and delete individual assets. - List multiple
assets with filters (e.g., by vendor, type, status) and pagination.
* Create, retrieve, update, and delete asset collections. - List
collections, filterable by vendor, with pagination.
# Billing API
Source: https://docs.topsort.com/en/ad-server/additional-apis/billing
Integrate with our Billing API
Topsort's [Billing API](/en/api-reference/billing-api) provides functionalities for managing billing aspects for both admins and vendors. Here's a list of its capacities:
* Get the current balance for a specific vendor. - Add funds to a vendor's
balance, including a description for the transaction. - Burn (reduce) a
vendor's balance for a specified reason. - List all wallets associated with
a vendor. - Create a new wallet for a vendor (limit of 3 per vendor). -
Adjust the balance of a specific wallet (add positive amount, burn negative
amount).
* Retrieve a list of all billing contacts, optionally filtered by vendor ID.
* Get details for a specific billing contact using its ID. - Create or
update (upsert) a billing contact's information. - Retrieve the billing
contact associated with a specific campaign. - Assign or update the billing
contact for a specific campaign. - Assign a billing contact to a specific
vendor. - Remove the assignment of a billing contact from a vendor.
# Campaign API
Source: https://docs.topsort.com/en/ad-server/additional-apis/campaign-api
Integrate with our Campaign API
Campaigns allow admins and vendors to promote products, banners or brands, using Topsort's UI and the [Campaign API](/en/api-reference/campaign-api).
If self-service is enabled, vendors can create campaigns themselves and submit
them for approval (for banner ads).
## Campaign Properties
These properties can be set on campaign creation using our API:
* Bidding Strategy
* Bids
* Budget
* Wallet
## Sponsored Listings
Campaigns designed for promoting products. A single campaign can have multiple products, and Topsort's algorithm will determine the best one to participate in auctions, depending on their quality scores and campaign objectives.
Each product of the campaign will have its own bid, and the bid participates in the auctions based on its triggers. There are three types of triggers:
1. **Set of products**: only bids that target the products listed in the set will participate in the auction.
2. **Category**: only bids that target products belonging to the given categories will have a chance to win the auction.
3. **Search term**: only bids that target products with matching keywords will have a chance to win such auctions.
## Banner and Video Ads
Banner and Videos Ads can be created to specific contexts of your platform: Landing Pages, Search and Category. Different placements can be created in each context, and each placement has different configurations.
### Landing Page Placements
Landing page placements allows you to create banner ads in different pages of your platform, without the need of targeting or filtering. These placements includes:
* **Slot ID**: an unique identifier of the placement.
* **Name**: a description of the placement, reference in the UI for placement selection.
* **URL or Deeplink**: the URL of the landing page.
* **Creative Width and Height, for two different dimensions**: desktop and mobile.
![Landing Page Slots]()
### Search and Categories Placements
Search and Categories placements allow you to create banner ads for targeting specific categories or keywords. These placements include:
* **Slot ID**: an unique identifier of the placement.
* **Creative Width and Height, for two different dimensions**: desktop and mobile.
![Search Slots]()
# Invitation API
Source: https://docs.topsort.com/en/ad-server/additional-apis/invitation-api
Integrate with our Invitation API
More APIs to customize your exact workflow and build your preferred version of an ad business. Check the complete documentation of our [Invitation API](/en/api-reference/invitation-api).
With this API, you can invite advertisers and vendors user accounts.
Send invitations using vendor ID and email.
Supports bulk invites (up to 500 at once).
Useful for onboarding new sellers into the ad platform.
# Offsite Ads API
Source: https://docs.topsort.com/en/ad-server/additional-apis/offsite
Integrate with our Offsite Ads API
Topsort's [Offsite Ads API](/en/api-reference/offsite-ads-api) provides functionalities for managing offsite ad campaigns, audiences, and reporting. This API includes:
* **Advertisers**: Create and retrieve advertiser details.
* **Audiences**: List, create, and upload users (via file) to audiences.
* **Campaigns**: List, create, retrieve details for, and update offsite campaigns.
* **Geotargeting**: Retrieve geotargeting settings for a specific campaign.
* **Jobs**: Check the status of asynchronous operations (like creation or uploads).
* **Reporting**: Get performance reports for campaigns, including overall summaries, daily breakdowns, and product-level details.
# Reporting API
Source: https://docs.topsort.com/en/ad-server/additional-apis/reporting-api
Integrate with our Reporting API
Topsort's [Reporting API](/en/api-reference/reporting-api) offers access to performance data across campaigns, vendors and marketplaces. You can download campaign and marketplace performance metrics such as:
* Daily or total reports for campaigns, vendors, products, or the entire marketplace.
* Scored attribution reports (via S3 links).
* Interaction reports: impressions, clicks, purchases by time granularity.
Reports are available at different contexts and levels of granularity:
## Campaign Reports
* Total campaign and daily breakdown performance reports, including campaign metrics such as ROAS, CTR and CPC.
* Reports with aggregated metrics by product can also be obtained.
* Campaigns KPIs: list of campaign level KPIs, with optional filtering by vendor, ad formats and other fields.
## Vendor Reports
* Total vendor and daily breakdown performance reports, including total impressions, clicks, purchases, ad spend and ROAS.
* Vendor level KPIs: list of vendor level KPIs.
## Marketplace Reports
* Aggregated report on the marketplace level.
* Also available with daily breakdown.
## Interaction Reports
* Allows exporting engagement (impressions, clicks, purchases) grouped by campaigns, products or vendors.
* Can optionally be aggregated by days or hours.
## Attribution Files
* Topsort provides scored attribution files.
* The files include impressions, clicks and purchases associated with campaign IDs, along with the attribution data.
* The files are available in parquet format, downloaded via pre-signed URLs.
# Algolia
Source: https://docs.topsort.com/en/ad-server/auctions/algolia
Integrate auction results with an existing Algolia index
This guide shows how to integrate Topsort auction results with your existing Algolia index, allowing organic and promoted products to be listed in the same flow.
Algolia is a powerful search engine that provides fast and relevant results for navigating catalogs. By integrating Algolia with Topsort, we can sync your catalog directly into Topsort, without needing extra catalog integrations. The integration will also enable you to prioritize promoted products in the organic results returned by Algolia. Check Topsort's Proxy integration for more details.
## How it Works
To integrate Topsort with Algolia, make sure you comply with these prerequisites:
* Your product catalog is stored in an Algolia index.
* You are querying Algolia using the Algolia SDK.
Create an Algolia API key with the following permissions: search, browse, listIndexes (additional permissions like addObject and deleteObject may be needed depending on how you manage your index updates).
* The browse permission enables downloading of your entire catalog.
* The listIndexes permission allows Topsort to check the index's last modification date to avoid unnecessary updates
Contact Topsort support and share your Algolia index name. This allows Topsort to configure and start importing your catalog.
Update your Algolia SDK configuration to point to Topsort's Proxy. This will allow Topsort to prioritize promoted products in the organic results returned by Algolia.
```javascript theme={null}
import algoliasearch from 'algoliasearch/lite';
const client = algoliasearch('YourApplicationID', 'YourWriteAPIKey', {
hosts: [{ url: 'myslug-sandbox.topsort.workers.dev' }],
});
const index = client.initIndex('your_index_name');
```
## Auction Results and Event Tracking
The promoted products prioritized in the response of Topsort's Proxy will have a resolvedBidId parameter that uniquely identifies that product's auction. You can use it to visually mark the product as "Promoted" for the end use.
The resolvedBidId is also needed to identify the auction winner when reporting events (impressions, clicks, purchases). Check our Events Tracking documentation for more detail.
# Auctions API
Source: https://docs.topsort.com/en/ad-server/auctions/auctions-api
Integrate with our Auctions API
Topsort's [Auctions API](/en/api-reference/auctions) 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.
# Catalog Integration
Source: https://docs.topsort.com/en/ad-server/catalog/index
Integrate your product catalog with Topsort to enable sponsored product campaigns
The Catalog is the foundation of your Topsort integration. Before running auctions or tracking events, you need to synchronize your product catalog with Topsort. This ensures that vendors can create campaigns for their products and that the auction system has accurate, up-to-date product information.
## Integration Options
Share your catalog using a product feed URL. Topsort automatically fetches and synchronizes your catalog data.
Use the Catalog API for real-time updates and programmatic control over your product data.
## What Gets Synchronized
Your catalog integration includes three key entities:
| Entity | Description | Required |
| -------------- | --------------------------------------- | -------- |
| **Products** | Items that can be promoted in campaigns | Yes |
| **Categories** | Product groupings for targeting | Yes |
| **Vendors** | Sellers who can create campaigns | Yes |
## Getting Started
Decide between a Product Feed (recommended for most integrations) or the Catalog API (for real-time programmatic updates).
Ensure your catalog data includes product IDs, names, categories, and vendor information.
Set up your product feed URL or implement API calls to keep your catalog up-to-date.
Check that products, categories, and vendors appear correctly in the Topsort platform.
## Next Steps
* [Set up a Product Feed](/en/ad-server/catalog/product-feed) - Recommended for most integrations
* [Use the Catalog API](/en/api-reference/catalog-api/upsert-products) - For programmatic updates
* [Learn about Catalog Management](/en/knowledge-base/ad-platform/catalog-management) - Best practices and configuration
# Product Feed
Source: https://docs.topsort.com/en/ad-server/catalog/product-feed
Integrate your product catalog with Topsort using a product feed
A product feed allows you to share your catalog with Topsort, synchronize data and maintain campaigns up-to-date. During the integration process you can provide us with the url of your product feed and we will ensure your catalog remains up to date. Our platform supports several formats:
* Google Product Data Specification.
* Tab separated values (TSV).
* Comma separated values (CSV).
![Topsort fetches data from a product feed]()
If your product catalog is already on a third-party platform like Algolia or VTEX, we can integrate directly with them for updates and synchronization, ensuring the product information is accurate. For detailed instructions on setting up these connections and specific requirements for each platform, please refer to the "3rd Party Integrations - Partners" section of our documentation.
## Google Product Data Specification
Share your catalog with Topsort using existing Google product feeds. We support the [Google Product Data Specification](https://support.google.com/merchants/answer/7052112?hl=en).
## TSV and CSV
We support sharing your catalog using TSV and CSV feeds. The instructions in this section apply to both formats.
**Which format should you use?**
We recommend you use TSV over CSV. CSV is more error prone due to commas often being present in the catalog data.
**If your product name or category name contains commas, you must use TSV.**
### Supported Columns
| Name | Required | Default | Description |
| :------------------------ | :---------------------------------- | :-------------------- | :----------------------------------------------------------------------------------------------------------------------------- |
| `id` | yes | - | Unique identifier for each product. |
| `active` | no | true | Whether the product can be part of campaigns or auctions. Inactive products will be removed from existing campaigns. |
| `title` | yes | - | Name of the product |
| `category.0.name` | yes | - | Category name of the primary category for this product. |
| `category.0.id` | no | Slug of category name | ID of the primary category for this product. |
| `vendor.0.name` | yes if not use `seller_name` | - | Vendor of the product. This is the entity that has their own budget to advertise this product and competes with other vendors. |
| `vendor.0.id` | yes if not use `external_seller_id` | Slug of vendor name | ID of the vendor of this product. |
| `seller_name` | yes if not use `vendor.0.name` | | Vendor name of the product, same value as `vendor.0.name`. |
| `external_seller_id` | yes if not use `vendor.0.id` | | ID of the vendor of this product. |
| `google_product_category` | yes | - | Categories provided in Google Taxonomy Format. |
| `product_type` | no | - | Additional taxonomy for the product. |
| `price` | no | - | Product price. |
| `image_link` | no | - | URL to an image of the product. |
| `link` | no | - | URL to the page of the product in the marketplace. |
| `availability` | no | - | Stock status. Must be one of `in stock`, `out of stock` or `preorder`. |
| `description` | no | - | Detailed description of the product. |
| `gtin` | no | - | Global Trade Item Numbers. Covers EAN, UPC, JAN, ISBN and ITF-14. |
| `brand` | no | - | Indicate the product's brand name. |
Categories can be provided in several ways. But only one is required.
You can associate a product with more categories and vendors. See the section below.
### File examples
#### Example TSV using vendor.0.name
```tsv theme={null}
id name description vendor.0.id vendor.0.name vendor.0.image_link category.0.id category.0.name category.1.id category.1.name image_link price availability
1293 Green Mask Green Mask for removing imperfections, use during night or day 1710000087 Derma Laboratories 10000087 Skin Care 61 Beauty & Health https://i.postimg.cc/0QxMWmbd/shampoo.png 23935.29 out of stock
1302 Cleanser Gel N/A 17829100 Shiny Laboratories 10000087 Skin care https://i.postimg.cc/0QxMWmbd/shampoo.png 16050.42 in stock
```
#### Example CSV using vendor.0.name
```csv theme={null}
id,name,description,vendor.0.id,vendor.0.name,vendor.0.image_link,category.0.id,category.0.name,category.1.id,category.1.name,image_link,price,availability
1293,Green Mask,"Green Mask for removing imperfections, use during night or day",1710000087,Derma Laboratories,,10000087,Skin Care,61,Beauty & Health,https://i.postimg.cc/0QxMWmbd/shampoo.png,23935.29,out of stock
1302,Cleanser Gel,N/A,17829100,Shiny Laboratories,,10000087,Skin care,,,https://i.postimg.cc/0QxMWmbd/shampoo.png,16050.42,in stock
```
### Multiple categories and vendors
Products can be associated with multiple categories and/or vendors.
As you might have noticed, the category and vendor columns contain indices. You can add additional category and/or vendor columns as long as you increase the index appropriately.
For example, a product with three categories and two vendors would have at the very least these columns:
```txt theme={null}
category.0.id
category.1.id
category.2.id
vendor.0.id
vendor.1.id
```
### Google Taxonomy Format
Alternatively, you can use [Google's Taxonomy Format](https://support.google.com/merchants/answer/7052112?hl=en#product_category) as category names. This allows you to describe more complex hierarchical relationships.
For example, this hierarchy:
```txt theme={null}
Apparel & Accessories > Clothing > Dresses
```
Will result in three categories:
```json theme={null}
[
{
"id": "apparel-and-accessories",
"name": "Apparel & Accessories",
"path": "apparel_and_accessories"
},
{
"id": "clothing",
"name": "Clothing",
"path": "apparel_and_accessories.clothing"
},
{
"id": "dresses",
"name": "Dresses",
"path": "apparel_and_accessories.clothing.dresses"
}
]
```
## Optional fields and auction optimization
The table above lists the minimum a product needs to participate in auctions. Beyond that minimum, we recommend including these fields for every product, since we use them to improve relevance and reporting:
* `description`
* `price`
* `link`
* `brand`
* `gtin`
## Hosting your product feed
Your product feed needs to be continuously accessible to Topsort so that we can keep our data up to date.
We can currently access public product feeds or feeds that are protected using [Basic HTTP Authorization](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Authorization).
In addition, use the [ETag Response headers](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/ETag) to help us determine if a product feed has been updated since last fetch.
## Deleting products
The `active` property can be set to `false` to mark a product as inactive. This can be done both [via the API](/en/api-reference/catalog-api/upsert-products) and via the product feed.
Inactive products will not be included in new campaigns or auctions. And will not be considered in any active campaigns. You can also set this when a product is out of stock, discontinued, or otherwise not available for sale.
To permanently delete products from Topsort's system, [use the API](/en/api-reference/catalog-api/delete-products) or omit them from the uploaded feed file.
## Generated slugs
When categories or vendors don't have an ID, we generate one on the fly.
**Prefer to use explicit IDs**
It's recommended to provide the IDs explicitly in your product feed, these IDs are used as references when managing campaigns and auctions.
If you use generated IDs you will need to use the same algorithm on the marketplace side to create such references.
These IDs use a **slug** derived from the name. A slug is a kebab case formatted string that is suitable for inclusion in URLs.
For example, `Hello world` becomes `hello-world`.
The format is based on the [npm slugify](https://www.npmjs.com/package/slugify) library.
## Dev Tools
Marketplaces that send their catalog via a product feed can open **Dev Tools > Catalog** in the marketplace Admin Dashboard to monitor ingestion health without opening a support ticket.
The Catalog tab surfaces key sync metrics at a glance:
* **Last sync time**: when the most recent catalog sync ran
* **Average sync duration**: how long syncs typically take
* **Success rate**: across the last 14 runs
* **Recent sync runs**: each ingestion with how many records were processed or skipped
With this view, engineering teams can confirm feeds are running on schedule and quickly spot failures or skipped-heavy runs.
# End-to-End API Example
Source: https://docs.topsort.com/en/ad-server/e2e-api-example
End to end integration example with our APIs
This example demonstrates a full flow using Topsort's APIs for a sponsored product campaign with category targeting. Replace API keys and IDs with your actual credentials and values.
**Steps:**
Sync your product catalog with Topsort
Set up a sponsored product campaign
Request auction winners
Report impressions, clicks, and purchases
Retrieve campaign performance data
* For managing products, campaigns, and reports, use an Advanced API Key
(TSC\_...). - For auctions and events, use a Marketplace API Key (TSE\_...).
## 1. Sync Catalog
A sample product example-product-coca-cola, from category soft-drinks is used in this example. Remember to use your Advanced API Key.
```javascript theme={null}
const apikey = "TSC_...";
const body = {
products: [
{
active: true,
categories: ["soft-drinks"],
id: "example-product-coca-cola",
imageURL:
"https://intl.cokestore.com/media/catalog/product/1/6/16181_squeeze-ko-can-maria-2.png",
name: "Coca Cola can",
price: "9.99",
vendors: ["coca-cola"],
},
],
};
try {
const response = await fetch(
"https://api.topsort.com/public/v1/catalog-search-service/catalogs/products",
{
method: "PUT",
mode: "cors",
headers: {
Authorization: `Bearer ${apikey}`,
"Content-Type": "application/json; charset=utf-8",
},
body: JSON.stringify(body),
}
);
if (!response.ok) {
console.error("unexpected status: " + response.status);
} else {
console.log("success status: " + response.status);
}
} catch (error) {
console.error(error);
}
```
## 2. Create Campaign
In this example, a campaign is created to promote the product example-product-coca-cola, having a keyword trigger (soft drink). Remember to use your Advanced API Key.
```javascript theme={null}
const apikey = "TSC_...";
const body = {
bids: [
{
target: {
type: "product",
id: "example-product-coca-cola",
},
triggers: [
{
type: "keyword",
value: {
matchType: "exact",
words: ["soft drink"],
},
},
],
},
],
budget: {
type: "daily",
amount: 10000,
},
campaignType: "autobidding",
isActive: true,
status: "approved",
adFormat: "listing",
name: "An example campaign",
};
try {
const response = await fetch(
"https://api.topsort.com/public/v1/campaign-service/campaigns?vendor_id=demo-vendor",
{
method: "POST",
mode: "cors",
headers: {
Authorization: `Bearer ${apikey}`,
"Content-Type": "application/json; charset=utf-8",
},
body: JSON.stringify(body),
}
);
if (!response.ok) {
console.error("unexpected status: " + response.status);
} else {
console.log("success status: " + response.status);
}
} catch (error) {
console.error(error);
}
```
## 3. Send Auction Request
In this example, an auction request is created to return winners triggered by the search term "soft drink". Remember to use your Marketplace API Key.
```javascript theme={null}
const apikey = "TSE_...";
const body = {
auctions: [
{
searchQuery: "soft drink",
slots: 1,
type: "listings",
},
],
};
try {
const response = await fetch("https://api.topsort.com/v2/auctions", {
method: "POST",
mode: "cors",
headers: {
Authorization: `Bearer ${apikey}`,
"Content-Type": "application/json; charset=utf-8",
},
body: JSON.stringify(body),
});
if (!response.ok) {
console.error("unexpected status: " + response.status);
} else {
console.log("success status: " + response.status);
}
} catch (error) {
console.error(error);
}
```
## 4. Tracking Events
In this example, a click on a promoted product is tracked using our API. The resolvedBidId of the winner returned by the auctions call needs to be sent in the body of the request, to guarantee correct attribution of sales. Remember to use your Marketplace API Key.
```javascript theme={null}
const apikey = "TSE_...";
const body = {
clicks: [
{
id: "d0cf3f56-a719-4e02-9c88-625f965ae6e7",
occurredAt: "2024-07-23T11:49:04+00:00",
opaqueUserId: "71303ce0-de89-496d-8270-6434589615e2",
resolvedBidId:
"ChAGafmNzX5wy4sEaDnXi4iWEhABjxq1RG513IkbvRgIVcd6GhABjmiyW3t2Ur066CLC3jWVIgoKBjExMjYzNBABMPuVDw",
},
],
};
try {
const response = await fetch("https://api.topsort.com/v2/events", {
method: "POST",
mode: "cors",
headers: {
Authorization: `Bearer ${apikey}`,
"Content-Type": "application/json; charset=utf-8",
},
body: JSON.stringify(body),
});
if (!response.ok) {
console.error("unexpected status: " + response.status);
} else {
console.log("success status: " + response.status);
}
} catch (error) {
console.error(error);
}
```
# Events API
Source: https://docs.topsort.com/en/ad-server/events/events-api
Track impressions, clicks, and purchases to enable attribution and campaign optimization
The Events API allows you to send real-time user interaction data to Topsort. This data powers campaign attribution, reporting, and optimization algorithms.
## Event Types
Topsort tracks three core event types:
| Event | Description | When to Send |
| -------------- | --------------------------------- | ---------------------------------------------- |
| **Impression** | User views a promoted product | When a sponsored product is rendered on screen |
| **Click** | User clicks on a promoted product | When a user clicks a sponsored product |
| **Purchase** | User completes a transaction | When an order is confirmed |
## Integration Options
Send events directly to Topsort's Events API for maximum control and flexibility.
Use our JavaScript SDK for easy client-side event tracking.
Route events through Segment if you're already using it for analytics.
Integrate via RudderStack for unified event routing.
## Key Concepts
### Resolved Bid ID
The `resolvedBidId` is a unique identifier returned from the Auctions API that links an event to a specific auction winner. This is required for impression and click events to enable proper attribution.
```json theme={null}
{
"impressions": [
{
"resolvedBidId": "WyJiX01mazE1IiwiMTJhNTU4MjgtOGVh...",
"occurredAt": "2023-05-01T12:00:00Z"
}
]
}
```
### Event Attribution
Events are attributed to campaigns based on:
* **Direct attribution**: User interacts with a promoted product and converts
* **Halo attribution**: User views a promoted product but purchases a different product from the same vendor
Learn more about [attribution models](/en/knowledge-base/ad-server/attribution).
## Implementation Steps
When displaying auction winners, store the `resolvedBidId` from the auction response.
Send an impression event when a sponsored product becomes visible to the user.
Send a click event when a user clicks on a sponsored product.
Send purchase events when orders are completed, including all purchased products.
## Example: Sending Events
```bash theme={null}
curl -X POST https://api.topsort.com/v2/events \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"impressions": [
{
"resolvedBidId": "WyJiX01mazE1IiwiMTJhNTU4...",
"occurredAt": "2023-05-01T12:00:00Z"
}
],
"clicks": [
{
"resolvedBidId": "WyJiX01mazE1IiwiMTJhNTU4...",
"occurredAt": "2023-05-01T12:00:05Z"
}
]
}'
```
## Next Steps
* [Events API Reference](/en/api-reference/events/report-events) - Full API documentation
* [Analytics.js Guide](/en/ad-platform/listings/analytics-js) - Client-side tracking
* [Attribution Models](/en/knowledge-base/ad-server/attribution) - Understanding attribution
# RudderStack
Source: https://docs.topsort.com/en/ad-server/events/rudderstack
Learn how to integrate Topsort Events with RudderStack
This guide explains how to set up Topsort as a destination in RudderStack. You can also check our documentation in [Rudderstack's Knowledge Base](https://www.rudderstack.com/docs/destinations/streaming-destinations/topsort/cloud-mode/).
1. In the RudderStack dashboard, add your data source (website or app).
2. From the list of destinations, select Topsort.
3. Complete the following settings:
| Setting | Description |
| ------- | ---------------------------------------------------- |
| Name | Unique name for this destination. |
| API Key | Obtain this on Topsort > Settings > API Integration. |
Click Set-up mapping in the dashboard to define how [RudderStack events](https://www.rudderstack.com/docs/event-spec/ecommerce-events-spec/) map to Topsort events. Example for mapping these events:
| RudderStack event | Topsort event |
| ------------------- | ------------- |
| Order Completed | Purchase |
| Product Clicked | Click |
| Product Added | Click |
| Product Viewed | Impression |
| Product List Viewed | Impression |
Prevent double-counting by reviewing your event firing logic.
Use `rudderanalytics.track()` to send events to Topsort.
Example:
```javascript theme={null}
rudderanalytics.track("Product Added", {
product_id: "9578257311",
sku: "8472-998-0112",
name: "Sample Product"
})
```
Check the mapping of all fields of each event in the Rudderstack's Knowledge Base
# Twilio Segment
Source: https://docs.topsort.com/en/ad-server/events/twilio-segment
Learn how to integrate Topsort Events with Twilio Segment
If you're using Twilio Segment to track events on your site, you can send events to Topsort directly by adding the Topsort Destination in your Segment account. Please refer to [Topsort documentation](https://segment.com/docs/connections/destinations/catalog/actions-topsort/) on the Twilio Segments knowledge base.
As a prerequisite for this integration, you must have a Segment account and a working Source (website or app).
Topsort uses three main events, all mapped from Segment's eCommerce Spec:
| Topsort Event | Default Segment Mapping | Alternate Mapping |
| :-----------: | :---------------------: | :-----------------: |
| `impressions` | Product Viewed | Product List Viewed |
| `clicks` | Product Clicked | Product Added |
| `purchases` | Order Completed | — |
* Avoid sending duplicated clicks. If both Product Clicked and Product Added are fired from the same user action, choose only one.
* If you're using custom events, reach out at [support@topsort.com](mailto:support@topsort.com) to map them properly.
1. In Segment, go to Connections > Catalog > Destinations
2. Search for Topsort, then click Add Destination
3. Select the relevant Source (your site or app)
![Segment App]()
1. In the Topsort Manager Platform, go to Settings > API Integration
2. Copy or create your Marketplace API Key
3. Back in Segment, open the Topsort destination's Settings tab and paste your API Key
![Segment Settings]()
The API Key allows Segment to send events to your Topsort account.
1. Only enable the Track events you're actively sending from your site
![Segment Mappings]()
Prevent double-counting by reviewing your event firing logic.
2. Add the `resolvedBidId` field to:
* Product Viewed events
* Product Clicked events
The `resolvedBidId` uniquely identifies the promoted winner of the auction. You can retrieve it from the Auctions API or Proxy response.
Example call:
```javascript theme={null}
analytics.track('Product Clicked', {
productId: '12345',
resolvedBidId: '67890' // required for Topsort attribution
});
```
Topsort recommends identifying logged users with Segment's identify method. Example:
```javascript theme={null}
analytics.identify('361b1fdfbeaa9d64a13c033eb9f970dc6740f6bc', {
email: 'john.doe@example.com'
});
```
Logged-out users are tracked with an `anonymousId`. If using server-side sources, include at least userId or anonymousId. Once a user is identified, each call to Segment's Track method automatically records the user ID. Users that are not logged in can be tracked using an anonymousId.
# Ad Server | Full API Integration
Source: https://docs.topsort.com/en/ad-server/index
Every feature and capacity we deliver can be used through our APIs
**Ad Server** is your complete API-first advertising solution, designed for businesses that need full control and customization. Every feature and capability Topsort offers is accessible through our comprehensive API suite, giving you maximum flexibility to build exactly what you need.
With Ad Server, you have complete control over auction logic, ranking algorithms, event tracking, and reporting. Perfect for companies with in-house development teams who want to deeply integrate advertising into their platform's unique architecture and workflows.
## Who Is This For?
Ad Server is ideal for:
* **Enterprises** with in-house engineering teams and custom requirements
* **Technical teams** needing full control over ad logic and ranking algorithms
* **Businesses** requiring deep integration with proprietary systems
* **Platforms** with unique auction mechanics or custom workflows
**Want a faster setup?** If you need quick deployment without extensive API integration, explore [Ad Platform](/en/ad-platform) instead.
## Key Benefits
Full control over every aspect
Build your own ranking algorithms
Integrate with proprietary systems
Access to all API capabilities
## Core APIs
Build your advertising platform using three foundational APIs:
### Catalog API
Keep your products, categories, and vendors synchronized with Topsort.
Manage product catalog data
Manage advertiser accounts
Organize product taxonomy
Keep catalog data current
### Auctions API
Trigger real-time bidding and retrieve winners for sponsored products and banners.
Real-time bidding mechanics
Sponsored product listings
Banner ad auctions
Handle auction results
### Events API
Track impressions, clicks, and purchases to enable optimization, reporting, and attribution.
Event tracking fundamentals
Track ad views
Track ad interactions
Track conversions and revenue
## Getting Started
New to Ad Server? Follow these steps:
1. **Set up your environment** - Get API credentials and configure authentication
2. **Sync your catalog** - Use the Catalog API to import products, vendors, and categories
3. **Implement auctions** - Integrate auction calls into your search and browse flows
4. **Track events** - Send impression, click, and purchase events to close the loop
5. **Test and optimize** - Monitor performance and refine your implementation
Start with [Authentication](/en/ad-server/authentication) to get your API credentials, then move to [Catalog API](/en/ad-server/catalog) to sync your products.
## Advanced Capabilities
Once you have the basics working, explore advanced features:
* **Custom ranking algorithms** - Implement your own logic for ad placement
* **A/B testing** - Run experiments on auction parameters and ranking strategies
* **Custom attribution models** - Build attribution logic that fits your business
* **Real-time reporting** - Create custom dashboards using our analytics endpoints
* **Multi-region deployments** - Scale across geographic regions
## Want Quick Setup Instead?
While Ad Server provides maximum flexibility and control, some businesses prefer a faster path:
* **Pre-built UI components** instead of custom development
* **Managed campaign tools** instead of custom workflows
* **Out-of-box reporting** instead of custom dashboards
* **Low-code integration** instead of full API implementation
If this describes your needs, explore [Ad Platform](/en/ad-platform) for pre-built tools and faster deployment.
# [BETA] Create Collection
Source: https://docs.topsort.com/en/api-reference/assets-api/[beta]-create-collection
/openapi.json post /public/v1/assets/collection
Creates a collection.
# [BETA] Delete Collection
Source: https://docs.topsort.com/en/api-reference/assets-api/[beta]-delete-collection
/openapi.json delete /public/v1/assets/collection/{collection-id}
Deletes a collection.
# [BETA] Get Collection
Source: https://docs.topsort.com/en/api-reference/assets-api/[beta]-get-collection
/openapi.json get /public/v1/assets/collection/{collection-id}
Retrieves a collection.
# [BETA] Get Collections
Source: https://docs.topsort.com/en/api-reference/assets-api/[beta]-get-collections
/openapi.json get /public/v1/assets/collections
Retrieves a list of collections.
# [BETA] Update Collection
Source: https://docs.topsort.com/en/api-reference/assets-api/[beta]-update-collection
/openapi.json patch /public/v1/assets/collection/{collection-id}
Updates a collection.
# Create Asset
Source: https://docs.topsort.com/en/api-reference/assets-api/create-asset
/openapi.json post /public/v1/assets/asset
Creates an asset.
# Delete Asset
Source: https://docs.topsort.com/en/api-reference/assets-api/delete-asset
/openapi.json delete /public/v1/assets/asset/{asset-id}
Deletes an asset.
# Get Asset
Source: https://docs.topsort.com/en/api-reference/assets-api/get-asset
/openapi.json get /public/v1/assets/asset/{asset-id}
Retrieves an asset.
# Get Assets
Source: https://docs.topsort.com/en/api-reference/assets-api/get-assets
/openapi.json get /public/v1/assets/assets
Retrieves a list of assets.
# Update Asset
Source: https://docs.topsort.com/en/api-reference/assets-api/update-asset
/openapi.json patch /public/v1/assets/asset/{asset-id}
Updates an asset.
# Adjust Wallet Balance
Source: https://docs.topsort.com/en/api-reference/billing-api/adjust-wallet-balance
/openapi.json post /public/v1/billing-service/vendors/{external-vendor-id}/wallets/{wallet-id}/adjust
Endpoint to change the balance for a wallet.
It will add the amount to the wallet if the amount is positive and burn the amount if it is negative.
The amount is ISO 4217 currency code compliant meaning that 100 as an input for USD marketplace will be 1 USD.
# Burn Vendor Balance
Source: https://docs.topsort.com/en/api-reference/billing-api/burn-vendor-balance
/openapi.json post /public/v1/billing-service/vendors/{external-vendor-id}/balance/burn
Endpoint to burn some amount of balance for a vendor.
# Delete Vendor Billing Contact
Source: https://docs.topsort.com/en/api-reference/billing-api/delete-vendor-billing-contact
/openapi.json delete /public/v1/billing-service/vendors/{external-vendor-id}/vendor-billing-contact/{billing-contact-id}
Endpoint to unassign a billing contact from a vendor.
# Get Billing Contact
Source: https://docs.topsort.com/en/api-reference/billing-api/get-billing-contact
/openapi.json get /public/v1/billing-service/billing-contacts/{billing-contact-id}
Endpoint to get a billing contact.
# Upsert Billing Contact
Source: https://docs.topsort.com/en/api-reference/billing-api/upsert-billing-contact
/openapi.json put /public/v1/billing-service/billing-contacts/{billing-contact-id}
Endpoint to upsert a billing contact.
# Endpoint to notify events generated in topsort
Source: https://docs.topsort.com/en/api-reference/endpoint-to-notify-events-generated-in-topsort
/openapi.json webhook webhooks
When an event is triggered we'll send you a POST request with this data.
Use the Webhooks API to manage the target url and the accepted events.
# [BETA] Campaign Performance Forecasts
Source: https://docs.topsort.com/en/api-reference/forecasting-service/[beta]-campaign-performance-forecasts
/openapi.json post /public/v1/toptimize/forecasting/campaign
Get campaign performance forecasts with confidence intervals.
> ⚠️ **Beta Access Required**
> Contact your sales representative to gain access to this endpoint and
> start using it.
**Currently Supported:**
- Listing campaigns (autobidding) only
**Returns total campaign forecasts (not daily) for:**
- Total impressions with confidence intervals
- Total clicks with confidence intervals
- Total purchases with confidence intervals
- Total sales with confidence intervals
- Total ad spend with confidence intervals
**Constraints:**
- Date range cannot exceed 31 days.
# [BETA] Invite Vendors
Source: https://docs.topsort.com/en/api-reference/invitation-api/[beta]-invite-vendors
/openapi.json post /public/v1/invitation-service/invitations
Invites a collection of Vendors to the Topsort platform.
The request payload should contain an array of pairs of vendor's ID, and
email.
# Create Slot
Source: https://docs.topsort.com/en/api-reference/media-api/create-slot
/openapi.json post /public/v1/media-service/slots
Create a new slot.
# Delete Banner Fallback
Source: https://docs.topsort.com/en/api-reference/media-api/delete-banner-fallback
/openapi.json delete /public/v1/media-service/slots/{slot-id}/fallback
Delete a banner fallback for a given slot.
# Delete Slot
Source: https://docs.topsort.com/en/api-reference/media-api/delete-slot
/openapi.json delete /public/v1/media-service/slots/{slot-id}
Delete an unused slot.
# Get Slots
Source: https://docs.topsort.com/en/api-reference/media-api/get-slots
/openapi.json get /public/v1/media-service/slots
Get slots for a given marketplace.
# Toggle Slot
Source: https://docs.topsort.com/en/api-reference/media-api/toggle-slot
/openapi.json patch /public/v1/media-service/slots/{slot-id}
Activate/Deactivate a slot.
# Create a new advertiser
Source: https://docs.topsort.com/en/api-reference/offsite-ads-api/create-a-new-advertiser
/openapi.json post /public/v1/offsite-ads/advertisers
Create a new advertiser.
# Create Campaign
Source: https://docs.topsort.com/en/api-reference/offsite-ads-api/create-campaign
/openapi.json post /public/v1/offsite-ads/campaigns
Create a new offsite campaign.
# Create Offsite Audiences Job
Source: https://docs.topsort.com/en/api-reference/offsite-ads-api/create-offsite-audiences-job
/openapi.json post /public/v1/offsite-ads/audiences/user-list
Create a new offsite audience job.
This endpoint creates a job to create an offsite audience alongside a presigned url to upload the audience csv file.
The presigned url is valid for 1 hour and should be used to upload the audience csv file.
The audience creation will begin once the csv file is uploaded.
The audience CSV should contain one or more of the following columns with hashed and normalized identifiers: hashed_email, hashed_phone, hashed_first_name, hashed_last_name, hashed_mobile_device_id. Strongest identifiers are hashed_email and hashed_phone. Hashing should use the SHA256 method. The audience will be synced to the specified DSPs.
# Delete Offsite Audience
Source: https://docs.topsort.com/en/api-reference/offsite-ads-api/delete-offsite-audience
/openapi.json delete /public/v1/offsite-ads/audiences/{audience-id}
Delete an existing offsite audience from Topsort as well as synced DSPs.
# Get Active Vendors
Source: https://docs.topsort.com/en/api-reference/offsite-ads-api/get-active-vendors
/openapi.json get /public/v1/offsite-ads/vendors/active
Get vendors that have at least one campaign created for the given DSP.
This endpoint returns a list of vendors that have at least one campaign created for the given DSP.
The list is paginated and the next page token is returned in the response.
The next page token can be used to get the next page of vendors.
# Get advertiser onboarding state for a specific DSP
Source: https://docs.topsort.com/en/api-reference/offsite-ads-api/get-advertiser-onboarding-state-for-a-specific-dsp
/openapi.json get /public/v1/offsite-ads/advertisers/{vendor-id}
Get advertiser onboarding state for a specific DSP.
# Get Campaign Aggregated Report
Source: https://docs.topsort.com/en/api-reference/offsite-ads-api/get-campaign-aggregated-report
/openapi.json get /public/v1/offsite-ads/reporting/campaigns/{campaign-id}
Get campaign report.
# Get Campaign Daily Report
Source: https://docs.topsort.com/en/api-reference/offsite-ads-api/get-campaign-daily-report
/openapi.json get /public/v1/offsite-ads/reporting/campaigns/{campaign-id}/daily
Get campaign daily report.
# Get campaign information
Source: https://docs.topsort.com/en/api-reference/offsite-ads-api/get-campaign-information
/openapi.json get /public/v1/offsite-ads/campaigns/{campaign-id}
Get campaign.
# Get Campaign Products Report
Source: https://docs.topsort.com/en/api-reference/offsite-ads-api/get-campaign-products-report
/openapi.json get /public/v1/offsite-ads/reporting/campaigns/{campaign-id}/products
Get campaign products report.
This endpoint returns a report of products that were advertised in a campaign.
Product level report is available for Google Ads campaigns only.
If the campaign is not a Google Ads campaign, It returns 404.
# Get Job Status
Source: https://docs.topsort.com/en/api-reference/offsite-ads-api/get-job-status
/openapi.json get /public/v1/offsite-ads/jobs/{job-id}
Get job status.
# Get Vendor Balances
Source: https://docs.topsort.com/en/api-reference/offsite-ads-api/get-vendor-balances
/openapi.json get /public/v1/offsite-ads/vendors/balances
Get vendor balances for the given vendors and DSP.
# Get vendor offsite campaigns
Source: https://docs.topsort.com/en/api-reference/offsite-ads-api/get-vendor-offsite-campaigns
/openapi.json get /public/v1/offsite-ads/campaigns
Get vendor offsite campaigns.
# List Offsite Audiences
Source: https://docs.topsort.com/en/api-reference/offsite-ads-api/list-offsite-audiences
/openapi.json get /public/v1/offsite-ads/audiences
List offsite audiences.
# Replace Offsite Audiences Job
Source: https://docs.topsort.com/en/api-reference/offsite-ads-api/replace-offsite-audiences-job
/openapi.json put /public/v1/offsite-ads/audiences/{audience-id}
Replace the contents of an existing offsite audience. This endpoint returns a new job id and presigned url for uploading the replacement audience CSV.
# Update Campaign
Source: https://docs.topsort.com/en/api-reference/offsite-ads-api/update-campaign
/openapi.json patch /public/v1/offsite-ads/campaigns/{campaign-id}
Update a campaign.
# Get Campaign Daily Report
Source: https://docs.topsort.com/en/api-reference/reporting-api/get-campaign-daily-report
/openapi.json get /public/v1/reporting-service/campaigns/{campaign-id}/daily
Endpoint to get a campaign's daily behavioral summary report between given dates.
# Get Campaign Report
Source: https://docs.topsort.com/en/api-reference/reporting-api/get-campaign-report
/openapi.json get /public/v1/reporting-service/campaigns/{campaign-id}
Endpoint to get a campaign's total behavioral summary report between given dates.
# Get Campaign Report By Product
Source: https://docs.topsort.com/en/api-reference/reporting-api/get-campaign-report-by-product
/openapi.json get /public/v1/reporting-service/campaigns/{campaign-id}/products
Endpoint to get a campaign's total behavioral summary report, divided by products, between given dates.
# Get Interactions Dump Urls
Source: https://docs.topsort.com/en/api-reference/reporting-api/get-interactions-dump-urls
/openapi.json get /public/v1/reporting-service/file-reports/interactions
Get interaction files for an specific date.
This endpoint returns a list of Amazon S3 pre-signed urls containing detailed interactions data in a parquet file format.
The files are available after 3am UTC and contains the interactions data for the previous day.
# Get Marketplace Campaigns Kpis
Source: https://docs.topsort.com/en/api-reference/reporting-api/get-marketplace-campaigns-kpis
/openapi.json get /public/v1/reporting-service/marketplace/campaigns-kpis
Get KPIs for campaigns in a marketplace using external vendor IDs.
# Get Marketplace Daily Report
Source: https://docs.topsort.com/en/api-reference/reporting-api/get-marketplace-daily-report
/openapi.json get /public/v1/reporting-service/marketplace/daily
Endpoint to get a marketplace's daily behavioral summary report between given dates.
# Get Marketplace Interactions Report
Source: https://docs.topsort.com/en/api-reference/reporting-api/get-marketplace-interactions-report
/openapi.json get /public/v1/reporting-service/interactions
Get interactions report for a marketplace grouped by entity type.
This endpoint returns detailed interaction data (impressions, clicks, purchases, etc.)
aggregated by the specified entity type (vendor, campaign, or product) and time granularity (daily or hourly).
Results can optionally be filtered to a single vendor or campaign.
The response is paginated to handle large datasets.
# Get Marketplace Report
Source: https://docs.topsort.com/en/api-reference/reporting-api/get-marketplace-report
/openapi.json get /public/v1/reporting-service/marketplace
Endpoint to get a marketplace's total behavioral summary report between given dates.
# Get Marketplace Vendors Kpis
Source: https://docs.topsort.com/en/api-reference/reporting-api/get-marketplace-vendors-kpis
/openapi.json get /public/v1/reporting-service/marketplace/vendors-kpis
Get KPIs for vendors in a marketplace using external vendor IDs.
# Get Product Daily Report
Source: https://docs.topsort.com/en/api-reference/reporting-api/get-product-daily-report
/openapi.json get /public/v1/reporting-service/campaigns/{campaign-id}/products/{product-id}/daily
Endpoint to get a product's daily behavioral summary report between given dates.
# Get Product Report
Source: https://docs.topsort.com/en/api-reference/reporting-api/get-product-report
/openapi.json get /public/v1/reporting-service/campaigns/{campaign-id}/products/{product-id}
Endpoint to get a product's total behavioral summary report between given dates.
# Get Scored Attribution Dump Urls
Source: https://docs.topsort.com/en/api-reference/reporting-api/get-scored-attribution-dump-urls
/openapi.json get /public/v1/reporting-service/file-reports/scored-attribution
Get scored attribution files for an specific date.
This endpoint returns a list of Amazon S3 pre-signed urls containing detailed attribution data in a parquet file format.
The files are available after 3am UTC and contains the attribution data for the previous day.
# Get Vendor Daily Report
Source: https://docs.topsort.com/en/api-reference/reporting-api/get-vendor-daily-report
/openapi.json get /public/v1/reporting-service/vendors/{vendor-id}/daily
Endpoint to get a vendor's daily behavioral summary report between given dates.
# Get Vendor Report
Source: https://docs.topsort.com/en/api-reference/reporting-api/get-vendor-report
/openapi.json get /public/v1/reporting-service/vendors/{vendor-id}
Endpoint to get a vendor's total behavioral summary report between given dates.
# Delete a segment.
Source: https://docs.topsort.com/en/api-reference/segments-service/delete-a-segment
/openapi.json delete /public/v1/segment-service/segments/{segment-id}
Delete a segment.
# Get upload users signed url for a segment.
Source: https://docs.topsort.com/en/api-reference/segments-service/get-upload-users-signed-url-for-a-segment
/openapi.json get /public/v1/segment-service/segments/{segment-id}/signed-url
Retrieve a signed URL for uploading a segment user file.
This endpoint returns a pre-signed URL that allows you to securely upload a segment user file.
File requirements:
- The file must be in plain text format (".txt").
- It should not contain headers.
- Each line must represent a single opaque user ID.
- The file must not exceed 50 MiB.
The signed URL can be used to upload the file directly via an HTTP PUT request.
For more information, see the [AWS documentation on uploading objects using presigned URLs](https://docs.aws.amazon.com/AmazonS3/latest/userguide/PresignedUrlUploadObject.html).
Returns
-------
dict: A dictionary containing the signed URL and any additional metadata required for upload.
# Retrieve a list of segments.
Source: https://docs.topsort.com/en/api-reference/segments-service/retrieve-a-list-of-segments
/openapi.json get /public/v1/segment-service/segments
Retrieve a list of segments.
# Retrieve a segment by ID.
Source: https://docs.topsort.com/en/api-reference/segments-service/retrieve-a-segment-by-id
/openapi.json get /public/v1/segment-service/segments/{segment-id}
Retrieve a segment by its external ID.
# Upload users to a segment.
Source: https://docs.topsort.com/en/api-reference/segments-service/upload-users-to-a-segment
/openapi.json post /public/v1/segment-service/segments/{segment-id}/upload
Uploads a file with segment users.
# Upsert segments with the provided information.
Source: https://docs.topsort.com/en/api-reference/segments-service/upsert-segments-with-the-provided-information
/openapi.json put /public/v1/segment-service/segments
Upsert segments with the provided information.
# Create User
Source: https://docs.topsort.com/en/api-reference/user-api/create-user
/openapi.json post /public/v1/user-service/advertiser-users
Create a user.
# Get User By Email
Source: https://docs.topsort.com/en/api-reference/user-api/get-user-by-email
/openapi.json get /public/v1/user-service/advertiser-users
Get a user by email.
# Update User
Source: https://docs.topsort.com/en/api-reference/user-api/update-user
/openapi.json put /public/v1/user-service/advertiser-users
Update a user vendor access. This will substitute accesses, so vendor ids not present in the update will be removed.
# Create Webhook
Source: https://docs.topsort.com/en/api-reference/webhooks-api/create-webhook
/openapi.json post /public/v1/webhooks/webhooks
Creates a webhook.
# Delete Webhook
Source: https://docs.topsort.com/en/api-reference/webhooks-api/delete-webhook
/openapi.json delete /public/v1/webhooks/webhooks/{webhook-id}
Deletes the webhook.
# Get Webhook
Source: https://docs.topsort.com/en/api-reference/webhooks-api/get-webhook
/openapi.json get /public/v1/webhooks/webhooks/{webhook-id}
Returns the webhook.
# Get Webhooks
Source: https://docs.topsort.com/en/api-reference/webhooks-api/get-webhooks
/openapi.json get /public/v1/webhooks/webhooks
Returns all webhooks.
# Update Webhook
Source: https://docs.topsort.com/en/api-reference/webhooks-api/update-webhook
/openapi.json patch /public/v1/webhooks/webhooks/{webhook-id}
Updates a webhook.
# Getting Started
Source: https://docs.topsort.com/en/overview/getting-started
Get started with your API Keys to begin integrating with Topsort
First you'll get access to your Topsort sandbox. To use our low-code
libraries, the main thing you need is a Marketplace API Key. It can be
created in the admin dashboard, at `Account Settings > API Integration`.
The Marketplace API Key is used for Actions and Events, while the Advanced
API Key is used for Catalog and other APIs.
![Create your API keys]()
In your Admin Dashboard, you can see logs of all API requests made with
your Marketplace and Advanced APIs.
![View activity log as you interact with the APIs]()
**Critical: Add budget before testing auctions!** Campaigns without sufficient budget cannot participate in auctions, leading to empty results. This is the most common integration issue. Ensure your account has a positive balance and campaigns have daily budgets set.
Before running your first auctions, make sure to:
* Add funds to your account balance
* Set appropriate daily budgets for your campaigns
* Monitor budget consumption in the dashboard
# Glossary
Source: https://docs.topsort.com/en/overview/glossary
Complete reference of retail media terminology covering auctions, campaigns, metrics, ROAS, attribution models, and ad optimization strategies
This glossary provides definitions for common terms used in retail media advertising and campaign management.
## Core Concepts
The catalog contains the items that will be promoted by advertisers. For retailers, these are products sold by 1P and 3P sellers.
Tools used by advertisers to promote products, enabling them to promote their catalog on the retailer's platform.
Every promoted item in a campaign is eligible for auctions. An auction requests the best options to fill a placement, considering optimization parameters for advertiser performance and retailer financial goals.
Purchases made by shoppers who interacted with an ad are attributed to campaigns. Parameters include attribution window and model (last click, multi-touch, etc).
## General Terms
The format or style of an advertisement. Common types include: Sponsored Listings, Banner Ads, Video Ads, Native Ads, etc.
The period of time in which conversions or sales are attributed to an ad. Varies by ad format: 7-14 days for Sponsored Listings, 14-30 days for Sponsored Brands, 14-30 days for Banner/Video Ads.
The type of device where the ad is viewed or interacted with: Mobile Web, Desktop, or App.
The specific location where the ad is displayed within a retail platform (e.g., homepage, search results, product pages).
Words or phrases used by customers in search queries that trigger ad placement (e.g., "running shoes," "laptop accessories").
Internal term for the unique identifier of a product in your catalog. Also called Product ID or SKU. In the API, this is the `id` field in product objects.
An anonymized user identifier used when you cannot share actual user IDs. Must be consistent across events for the same user session to enable attribution.
Fraudulent or bot traffic that should be filtered from reporting. Marketplaces are responsible for filtering SIVT before sending events to Topsort.
## Performance Metrics
The total number of times an ad is shown to users.
The number of times users clicked on an ad for which an advertiser will be billed.
The percentage of impressions that result in clicks. **Formula:** CTR = (Clicks ÷ Impressions) × 100
The average cost per click. **Formula:** Average CPC = Total Ad Spend ÷ Total Clicks
The total cost of the campaign, including all ad clicks and associated charges.
The total revenue generated from purchases as a result of the ad campaign.
The total number of completed orders resulting from clicks on the ad.
The total number of individual items sold as a result of the ad campaign.
The percentage of users who completed a purchase after clicking on the ad. **Formula:** Conversion Rate = (Sales ÷ Clicks) × 100
## Advanced Metrics
The total revenue generated per dollar spent on ads. **Formula:** ROAS = Sales ÷ Total Ad Spend
A ROAS of 3.0 means $3 in revenue for every $1 spent on advertising.
The ROAS for the same product (SKU) that was clicked. Tracks revenue generated per dollar spent specifically on the clicked SKU.
The ROAS for products from the same brand that were clicked. Used to track brand lift and halo effects.
## Cost & Pricing Models
The cost per thousand impressions. A pricing model where advertisers pay for every 1,000 times their ad is shown.
**Formula:** CPM = (Total Ad Spend ÷ Impressions) × 1,000
The cost an advertiser pays each time a user clicks on their ad. A performance-based pricing model where payment occurs only when the ad is clicked.
**Formula:** CPC = Total Ad Spend ÷ Total Clicks
The cost to acquire a customer through an ad campaign.
**Formula:** CPA = Total Ad Spend ÷ Conversions (Sales)
The average value of an order generated from an ad click.
**Formula:** AOV = Sales ÷ Orders
The average position of an ad relative to other ads in a given placement. Higher rank means better visibility.
The percentage of total ad impressions captured by a brand versus competitors.
**Formula:** SOV = (Your Impressions ÷ Total Market Impressions) × 100
## Attribution Models
Attribution model where the final ad click before a purchase is credited with the sale. Most common model for direct response campaigns.
Attribution model where credit is given to multiple touchpoints throughout the customer journey. Useful for understanding the full path to purchase.
Attribution model where credit is given to ads shown but not clicked, influencing a purchase after the fact. Common for awareness campaigns.
Attribution model where a vendor receives credit when a user clicks on Product A but purchases Product B from the same vendor. Requires `vendorId` in purchase events.
The unique identifier returned from an auction that connects events (impressions, clicks, purchases) back to the winning bid for attribution purposes.
## Campaign Management
Changes made to bids to optimize ad placement, typically based on factors like time of day, device type, location, or keyword performance.
The distribution of ad spend across different campaigns, keywords, or placements to maximize ROI.
The average total spend across all campaigns or ads.
**Formula:** Average Ad Spend = Total Ad Spend ÷ Number of Campaigns
The unique product identifier (e.g., SKU, UPC, or ASIN) associated with the product(s) being advertised.
The dimensions and format of the ad creative (e.g., 970x90, 300x250 pixels for banner ads, 16:9 for video ads).
## Ad Formats
Ads that appear within product search results or category pages, typically appearing as "sponsored" or "promoted" products. High purchase intent format.
Ads displayed in fixed sections of a webpage, such as at the top, side, or bottom of the page. Used for awareness and discovery.
Ads designed to blend seamlessly with the content of the website or platform, making them look like part of the organic content (e.g., sponsored articles).
A type of ad that allows multiple products to be displayed in a sliding format. Often used for showcasing different product variations or collections.
Ads targeted at users who have previously interacted with the brand or product but have not yet converted.
# Going Live
Source: https://docs.topsort.com/en/overview/going-live
Complete guide to preparing for and executing a smooth transition to production with comprehensive testing and monitoring strategies.
Before moving to production, conduct thorough User Acceptance Tests (UAT) to ensure a smooth transition. This guide walks you through pre-launch preparation, testing procedures, deployment steps, and post-launch monitoring.
**Your go-live process may vary** depending on your integration path and ad formats. This guide covers the most common scenarios, but your specific implementation may differ. For example:
* **Sponsored Listings** require full catalog integration with product data
* **Banner Ads** may only require vendor/advertiser setup without product-level catalog
* **Placement configurations** vary based on your ad format choices
Work with your Topsort contact to confirm which sections apply to your integration.
## Pre-Launch Checklist
* [ ] Product feed is connected and updating regularly
* [ ] All product attributes (id, name, price, image, category) are populated
* [ ] Product availability is accurate
* [ ] Category taxonomy is properly mapped (based on your agreed taxonomy structure)
* [ ] Auction requests include all required fields
* [ ] Response handling is implemented
* [ ] Impression tracking fires when sponsored products are visible
* [ ] Click tracking fires on product clicks (including "Add to Cart" if applicable)
* [ ] Purchase events include all order details
* [ ] User IDs are consistent across all events
* [ ] Vendors/advertisers are configured in the system
* [ ] Placements or JSON templates are created in the system
* [ ] Banner creative assets are uploaded and approved
* [ ] Click-through URLs are configured correctly
* [ ] (Optional) content standards are uploaded to the system
* [ ] Auction requests include all required fields
* [ ] Banner placement IDs are correctly configured
* [ ] Response handling returns banner creative data
* [ ] Banner rendering logic is implemented
* [ ] Impression tracking fires when banner is visible
* [ ] Click tracking fires on banner clicks
* [ ] User IDs are consistent across all events
### Common Configuration (All Ad Formats)
**API Credentials:**
* [ ] Sandbox API keys are properly configured
* [ ] Production API keys are ready (don't switch yet)
* [ ] API keys are stored securely in environment variables
* [ ] Key rotation process is documented
**Environment Setup:**
* [ ] Staging environment mirrors production configuration
* [ ] All API endpoints are configured correctly
* [ ] Timeout values are appropriate (recommended: 500-1000ms)
* [ ] Error handling is implemented
**Ad Display:**
* [ ] Ad placements render correctly on all device types
* [ ] Ad labels are clearly visible (see labeling guidelines below)
* [ ] Ad images/creatives load properly with fallbacks
* [ ] Click-through behavior works as expected
**Performance:**
* [ ] Page load times are acceptable with ads
* [ ] Ads don't block critical page rendering
* [ ] Mobile experience is optimized (touch targets, responsive layouts, fast load times)
* [ ] Accessibility requirements are met
**Instrumentation:**
* [ ] Error tracking is configured (Sentry, Datadog, etc.)
* [ ] Performance monitoring is in place
* [ ] Custom dashboards are set up
* [ ] Alerting thresholds are defined
**Logging:**
* [ ] API request/response logging is enabled
* [ ] Error logs are being captured
* [ ] Audit trail for ad events is configured
* [ ] Log retention policies are set
### Ad Labeling Guidelines
Use labels that clearly indicate promotional content while avoiding ad-blocker triggers:
* **"Featured"**
* **"Recommended"**
* **"Client's Choice"**
* **"Top Pick"**
Avoid using "Sponsored" or "Ad" as these terms are commonly targeted by ad blockers.
If operating in the European Union, the **Digital Services Act (DSA)** requires:
* [ ] Clear labeling that content is an advertisement
* [ ] Display of the advertiser name in ad details
* [ ] Transparency about why the ad was shown to the user
Work with your legal team to ensure full DSA compliance.
## User Acceptance Testing (UAT)
### 1. Catalog Testing
**In Topsort Admin Panel:**
1. Navigate to Catalog section
2. Verify products are visible and searchable
3. Check that product data is complete:
* Product names, images, and prices are correct
* Categories are properly assigned
* Product availability status is accurate
**Test Campaign Creation:**
1. Create a new test campaign named `UAT-TEST-[DATE]`
2. Try adding products to the campaign
3. Verify product search and filtering works
4. Confirm product selection saves correctly
**Expected Result:** All products should be selectable when creating campaigns, with accurate and complete information.
**In Topsort Admin Panel:**
1. Navigate to Vendors/Advertisers section
2. Verify vendors are configured correctly
3. Verify click-through URLs are correct
**Test Campaign Creation:**
1. Create a new test campaign named `UAT-TEST-[DATE]`
2. Select banner ad format
3. Configure targeting and bid settings
4. Activate the campaign
**Expected Result:** Banner campaigns should be creatable with proper creative assets and targeting options.
### 2. Auctions & Events Testing
**Setup:**
* Create `UAT-TEST` campaign with 3-5 products
* Set high bid amount (\$10+) to ensure wins
* Activate the campaign
**Test Scenarios:**
1. Verify auction request is sent
2. Check that winning products are returned
3. Confirm products render on page
**Validation:**
* Check browser network tab for API calls
* Verify auction response contains products
* Ensure resolvedBidId is captured for event tracking
**Test All Event Types:**
**Impression Events:**
* Load page with sponsored products
* Verify impression event fires when ad is visible
* Check resolvedBidId is included
**Click Events:**
* Click on sponsored product
* Verify click event fires immediately
* **Note:** "Add to Cart" actions also count as clicks if configured
* Confirm navigation/action works correctly
**Purchase Events:**
* Complete a purchase with sponsored product
* Verify purchase event includes:
* Product ID and quantity
* Order value and order ID
* **User ID** (required for attribution)
**Setup:**
* Create `UAT-TEST` banner campaign
* Set high bid amount to ensure wins
* Activate the campaign
**Test Scenarios:**
1. Load page with banner placement
2. Verify auction request is sent
3. Check that winning banner creative is returned
4. Confirm banner renders correctly on page
**Validation:**
* Check browser network tab for API calls
* Verify auction response contains banner data
* Ensure resolvedBidId is captured for event tracking
**Test All Event Types:**
**Impression Events:**
* Load page with banner placement
* Verify impression event fires when banner is visible
* Check resolvedBidId is included
**Click Events:**
* Click on banner
* Verify click event fires immediately
* Confirm click-through URL navigation works
**Note:** Purchase events may not apply to banner-only integrations unless you're tracking downstream conversions.
**Test with Two Different Users:** Perform all tests with at least two unique user sessions to verify proper user tracking and attribution.
### 3. Data Validation
**For Each Test User:**
* Take screenshots of ad placements
* Capture network requests showing API calls
* Document order details for purchase events (if applicable)
* Note timestamps for each action
Send the following to your Topsort contact:
* Screenshots of ad impressions
* Network logs showing auction and event calls
* Test campaign name and time range
* User identifiers used in testing
Topsort will provide a summary including:
* Total auctions received
* Impression and click counts
* Purchase counts (for listing ad integrations)
* Data quality score
* Any data discrepancies or issues
**Verify Alignment:**
* Numbers match your test actions
* Attribution chain is complete
* No missing or duplicate events
## Production Deployment
### Deployment Steps
**Option 1: Product Feed**
* Share your production feed URL with Topsort
* Ensure feed is accessible and updates regularly
* Recommended update frequency: Every 15-60 minutes
**Option 2: Catalog API**
* Use the [Catalog API](/en/ad-server/catalog/) for real-time updates
* Implement create, update, and delete operations
* Set up scheduled full catalog sync
**Verify:**
* Product count matches expectations
* All required fields are populated
* Images are loading correctly
**Vendor Setup:**
* Confirm all vendors/advertisers are configured
* Verify banner creatives are uploaded and approved
* Check click-through URLs are production-ready
**Verify:**
* All active vendors are visible in admin
* Banner creatives display correctly
* Targeting options are configured
**Using Topsort UI:**
1. Topsort provides admin panel credentials
2. You receive production API URL
3. [Generate API keys](/en/api-reference/authentication) in admin
4. Store keys securely in production environment
**Using Custom UI:**
1. Receive production API URL from Topsort
2. Receive production API key(s)
3. Configure keys in your environment
**Never commit API keys to version control.** Use environment variables or secure secret management systems.
**Pre-Deployment:**
* Review all code changes one final time
* Ensure sandbox credentials are parameterized
* Confirm rollback procedure is documented
* Schedule deployment during low-traffic period
**Deployment Process:**
1. Deploy code to production environment
2. Update environment variables with production credentials
3. Restart services to pick up new configuration
4. Verify application starts successfully
**Immediate Verification:**
* Check application logs for errors
* Test basic functionality (page loads)
* Verify API connectivity
### Traffic Ramping Strategy
**Recommended Approach:**
**Day 1-2:** 10% of traffic
* Monitor closely for errors
* Validate data accuracy
* Check performance metrics
**Day 3-5:** 50% of traffic
* Compare metrics with baseline
* Ensure system stability
* Fine-tune if needed
**Day 6+:** 100% of traffic
* Full production launch
* Continue monitoring
* Optimize performance
**Use Feature Flags to Control:**
* Which placements show ads
* Percentage of users seeing ads
* A/B testing configurations
* Emergency kill switch
**Benefits:**
* Instant rollback without deployment
* Gradual rollout control
* Per-placement configuration
* Reduced deployment risk
## Post-Launch Monitoring
### Critical Metrics to Monitor
**API Performance:**
* Auction API response time (target: \<500ms p95)
* Event API success rate (target: >99.5%)
* Error rates and types
* API timeout frequency
**Application Performance:**
* Page load time impact
* Time to first ad render
* JavaScript errors
* Memory usage patterns
**Action Items if Issues Detected:**
* Response time >1s: Review timeout settings
* Error rate >1%: Check API credentials and network
* High JS errors: Review client-side implementation
**Event Tracking:**
* Impression-to-click ratio (typical: 1-5%)
* Click-to-purchase ratio (typical: 2-10%, for listing ads)
* Event volume consistency
* Attribution completeness
**Data Integrity:**
* User IDs are present and consistent
* resolvedBidIds are captured for impressions and clicks
* Purchase amounts are reasonable (listing ads)
* Duplicate events are minimal
**Dashboard Checks:**
* Compare Topsort dashboard with your analytics
* Verify revenue attribution matches
* Check for data gaps or spikes
**Campaign Performance:**
* Total impressions delivered
* Click-through rate (CTR)
* Conversion rate (listing ads)
* Return on ad spend (ROAS)
**User Experience:**
* Ad viewability rates
* User engagement with ads
* Impact on organic conversion rate
* Page bounce rate changes
**Revenue Impact:**
* Incremental revenue from ads
* Average order value changes
* Vendor adoption rate
* Campaign creation velocity
### Troubleshooting Common Issues
**Possible Causes:**
* No active campaigns
* Bid amounts too low
* Product targeting too narrow
* Auction API errors
**Debugging Steps:**
1. Check browser console for errors
2. Verify auction API response
3. Confirm campaigns are active
4. Review targeting criteria
**Possible Causes:**
* Event not triggered on checkout
* Missing user ID in event payload
* Incorrect product ID format
* Network failures
**Debugging Steps:**
1. Test purchase flow manually
2. Check event payload structure
3. Verify user ID is included
4. Review server logs
**Possible Causes:**
* No active banner campaigns
* Bid amounts too low
* Banner creative not approved
* Auction API errors
**Debugging Steps:**
1. Check browser console for errors
2. Verify auction API response
3. Confirm campaigns are active
4. Check creative approval status
**Possible Causes:**
* Creative URL inaccessible
* Image format not supported
* CORS issues
* Container sizing issues
**Debugging Steps:**
1. Check creative URL directly
2. Verify image loads in browser
3. Check network tab for CORS errors
4. Review container CSS
**Possible Causes:**
* Slow API responses
* Blocking auction calls
* Large image files
* Too many placements
**Solutions:**
1. Implement proper timeouts
2. Use async/non-blocking calls
3. Optimize image loading
4. Cache auction responses
**Possible Causes:**
* Double-counting events
* Missing attribution chain
* Time zone mismatches
* Bot traffic
**Investigation:**
1. Compare raw event counts
2. Check for duplicate IDs
3. Verify timezone handling
4. Review user agent filtering
## Best Practices
**Internal Coordination:**
* Notify engineering team of deployment
* Alert customer support of new features
* Update sales team on capabilities
**External Communication:**
* Coordinate with Topsort team
* Schedule launch calls
* Establish escalation paths
**Maintain:**
* Deployment runbooks
* Rollback procedures
* API integration specs
* Troubleshooting guides
**Keep Updated:**
* Configuration changes
* Known issues and workarounds
* Performance benchmarks
**Continuous Improvement:**
* Review performance weekly
* Optimize slow queries
* Refine targeting
* Test new placements
**A/B Testing:**
* Ad placement positions
* Number of ads per page
* Ad formats and styles
* Targeting strategies
**Establish:**
* On-call rotation
* Incident response process
* Topsort escalation contacts
* SLA expectations
**Document:**
* Common support scenarios
* Resolution procedures
* Contact information
***
Once you're live, you're ready to start optimizing. Reach out to your Topsort contact for guidance on campaign strategies, attribution tuning, and advanced configurations.
# Welcome to Topsort
Source: https://docs.topsort.com/en/overview/index
Discover Topsort's integration options and core products to launch, scale, and optimize your retail media business with privacy-focused, flexible, and AI-powered solutions
This guide provides information on Topsort's suite of products designed to
enhance the growth of your retail media networks. You can choose the module
and integration path that best suits your needs. This Integration Guide contains
all the details you need to get started with Topsort's offerings. For in-depth
explanations of features and concepts, visit the [**Knowledge Base**](/en/knowledge-base/).
Consider this your essential resource for launching, scaling, and optimizing
your retail media business. Whether you are new to advertising, upgrading
existing systems, or aiming to improve results with AI-powered tools, you will
find the necessary technical information here to connect with Topsort's
infrastructure.
## What is Topsort's Retail Media Infrastructure
Topsort enables the creation of a unique advertising ecosystem through four
core components:
A comprehensive, ready-to-use solution for launching, growing, and
activating your advertising business. It includes tools for managing
campaigns, viewing reports, tracking results, and integrating ad displays.
Offers powerful APIs for customizing ads and integrating with existing
systems and software. This ensures a seamless experience for sellers while
allowing them to control ad relevance, audience targeting, and performance
improvement.
Provides smart tools and individual components to enhance your ad system,
including solutions for forecasting, retrieval, and attribution to address
challenges common to large online platforms.
Topsort's DSP for advertising agencies and brands, enabling campaign
management across multiple online retailers from a centralized platform
with real-time data and AI-powered enhancements.
## Choosing the Right Path
* For those new to retail media, start with the [**Ad Platform's low-code
tools**](/en/ad-platform/).
* For building custom logic, explore the [**Ad Server APIs**](/en/ad-server/).
* For programmatic scaling, utilize [**Toppie for demand-side
expansion**](/en/toppie/).
* For migrating systems, review [**fallback strategies and A/B testing
guidelines**](/en/advanced-integrations/).
Topsort offers state-of-the-art, privacy-focused technology to help retailers
build and expand their ad businesses. To accommodate various technical skills
and preferences, two main integration methods are available:
* **Low-Code Integration**: Offers a simpler, more direct setup.
* **Full API-First Integration**: Provides maximum flexibility and
customization.
Regardless of the chosen integration path, Topsort equips you with the tools
to monetize through an omnichannel ad system. Each integration component is
designed to assist in managing, understanding, and improving your advertising
strategies.
For detailed guides, step-by-step instructions, and personalized support,
please contact our technical support team via the [**Support
Portal**](https://help.center.topsort.com/servicedesk/customer/portal/1).
We are committed to ensuring a smooth integration process and helping you
maximize the potential of your inventory.
# Integration Overview
Source: https://docs.topsort.com/en/overview/integration-overview
An overview to the integration process
There are core elements of a successful Topsort integration. First, gain
access to your Topsort sandbox from your Topsort representative. Based on your
product access, you will be able to have API keys that will unlock the
following key components of a product integration:
Obtain API keys (Marketplace for low-code, Advanced for catalog/CRM) from
your Topsort dashboard.
Topsort offers two integration approaches to fit your technical requirements and timeline:
* **Low-code integration ([Ad Platform](/en/ad-platform))**: Use our pre-built SDKs, libraries, and plugins for fast implementation
and minimal development effort. Perfect for marketplaces that want to launch quickly.
* **API-first integration ([Ad Server](/en/ad-server))**: Leverage our
powerful set of public APIs to gain full control of your ad setup. Ideal for enterprises with in-house teams and custom requirements.
| Feature | Ad Platform (Low-Code) | Ad Server (API-First) |
| ----------------------- | ------------------------------- | ------------------------------ |
| **Setup Time** | Days to weeks | Weeks to months |
| **Development Effort** | Minimal | Significant |
| **Customization** | Standard features only | Full control over all aspects |
| **Target Audience** | Marketplaces, product teams | Enterprises, technical teams |
| **Campaign Management** | Pre-built UI and tools | Build your own interface |
| **Ad Formats** | Banners, sponsored listings | Any format you design |
| **Best For** | Quick launch, standard features | Custom logic, deep integration |
**Choose [Ad Platform](/en/ad-platform) if you:**
* Want to launch retail media quickly with minimal development
* Prefer pre-built campaign management tools and reporting dashboards
* Need standard banner ads and sponsored product listings
* Have limited in-house development resources
* Want to use platform plugins (VTEX, Salesforce) for easy integration
**Choose [Ad Server](/en/ad-server) if you:**
* Need complete control over auction logic and ranking algorithms
* Have in-house engineering teams to build custom solutions
* Require deep integration with proprietary systems
* Want to implement custom ad formats or unique workflows
* Need advanced features like custom attribution models or A/B testing frameworks
Use built-in logging and staging environments to monitor requests.
Deploy to production and leverage Topsort's analytics for optimization.
# Pick an integration path
Source: https://docs.topsort.com/en/overview/pick-an-integration-path
Choose between Low Code Integration with SDKs for quick setup, or API-first integration for full customization and control
We offer two integration paths, depending on which ad formats you plan on
integrating (banners, listings), how much customization you need and how fast
you want to go live.
If you're going for a simple ad platform integration, we recommend **Low
Code Integration** using our SDKs and libraries. The libraries we offer
include:
* **[Banners.js](/en/ad-platform/banners/bannersjs)**: for rendering banner ads. Can also be injected using [Google Tag Manager](/en/ad-platform/banners/google-tag-manager).
* **[Analytics.js](/en/ad-platform/listings/analytics-js)**: for tracking clicks, impressions and purchases.
* **[Javascript SDK](/en/ad-platform/sdks/javascript-sdk)**: optional low-code wrapper for auctions and events.
* **[Topsort Proxy](/en/ad-platform/listings/topsort-proxy)**: handles injection of auction winners into your catalog or search engine results.
If you're going for an ad server integration and ad intelligence, we
recommend an **API-first integration path**. APIs offered today:
* **[Catalog API](/en/ad-server/catalog)**: keep Topsort up-to-date with your catalog changes.
* **[Auctions API](/en/ad-server/auctions/auctions-api)**: request winners for banners or listings.
* **[Events API](/en/ad-server/events/events-api)**: track clicks, impressions and purchases.
Additional APIs:
* **[Invitation API](/en/ad-server/additional-apis/invitation-api)**: invite advertiser users to the platform.
* **[User API](/en/ad-server/additional-apis/user-api)**: manage advertiser users.
* **[Reporting API](/en/ad-server/additional-apis/reporting-api)**: get granular reporting about your campaigns.
* **[Campaign API](/en/ad-server/additional-apis/campaign-api)**: create and update banner and listing campaigns.
* **[Segments API](/en/ad-server/additional-apis/segments-api)**: create and manage user segments, for campaign targeting.
* **[Webhooks API](/en/ad-server/additional-apis/webhooks-api)**: create and manage webhooks, for personalized campaign events.
* **[Billing API](/en/ad-server/additional-apis/billing)**: top-up vendor, create wallets, add and manage billing contacts.
* **[Assets API](/en/ad-server/additional-apis/assets-api)**: create and manage assets like images and videos.
* **[Offsite API](/en/ad-server/additional-apis/offsite)**: manage advertisers, campaigns and metrics related to offsite campaigns.
# Segments API
Source: https://docs.topsort.com/en/ad-server/additional-apis/segments-api
Integrate with our Segments API
Topsort's [Segments API](/en/api-reference/segments-service) allows our clients to create and manage groups of users for targeting purposes. After creating segments on our platform, they can be used as targeting in the campaign creation.
## Uploading Users to a Segment
Once a segment is created, users can be uploaded to it using our APIs. Topsort support three actions:
* **Add**: Append new users to the existing segment, without making changes to existing ones.
* **Remove**: Delete specific users from the segment.
* **Replace**: Overwrite the entire segment with a new user list
User lists must follow this specification:
* File format is .txt
* No headers
* One Opaque User ID per row, without emails or personal information.
## Use in Campaigns
Segments are used as targeting options in campaigns. The same Opaque User ID uploaded to the segments should be used on the auction request, to guarantee the auction engine can match it with the corresponding segment.
# User API
Source: https://docs.topsort.com/en/ad-server/additional-apis/user-api
Integrate with our User API
More APIs to customize your exact workflow and build your preferred version of an ad business. Check the complete documentation of our [User API](/en/api-reference/user-api).
With this API, you can manage advertisers and vendors user accounts.
Create, retrieve, and update users via email.
Assign or modify vendor-level permissions.
Useful for managing team access and roles.
# Webhooks API
Source: https://docs.topsort.com/en/ad-server/additional-apis/webhooks-api
Integrate with our Webhooks API
Topsort's [Webhooks API](/en/api-reference/webhooks-api) allows you to configure webhooks for receiving automated notifications about specific events, such as campaign updates. With this API you can:
* Subscribe to platform events (e.g. campaign updates).
* Create, update, delete, and retrieve webhook configurations
# Fallback and A/B Testing
Source: https://docs.topsort.com/en/advanced-integrations/index
Run Topsort alongside existing ad servers with fallback logic
If the retailer already is running ads using an ad server, it is possible to run it alongside Topsort using a fallback logic. This allows retailers to compare ad servers performance and increase fill-rates.
## Use Cases
Use a secondary ad server when Topsort returns no winners, ensuring maximum
fill rate
Compare ad server performance using audience segments or traffic splits
## How It Works
For instance, if the retailer is running banner ads using GAM (Google Ad Manager), they can set Topsort as the primary ad server to make sure their direct sold campaigns have priority over GAM's demand.
Ad requests and interactions coming from ads not served by Topsort can be reported to Topsort to see and compare metrics in one place.
Set up Topsort as your primary ad server using any of the integration
methods (API, SDK, or low-code).
Always request an ad from Topsort first in your ad serving logic.
If Topsort returns winners, display the Topsort ad.
If no winners are returned, request an ad from your secondary ad server.
## Implementation Example
```javascript theme={null}
async function displayAd() {
try {
const response = await fetch("https://api.topsort.com/v2/auctions", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
// Your auction request parameters
}),
});
const auctionData = await response.json();
if (auctionData?.results?.winners) {
console.log("Topsort ad displayed.");
return; // Exit early - Topsort ad is displayed
} else {
console.log("No Topsort ad available.");
}
} catch (error) {
console.error("Error fetching Topsort ad:", error);
}
// Fallback to secondary network
if (secondaryNetwork) {
// Render ad from secondary network
console.log("Displaying secondary ad.");
} else {
console.warn("No secondary ad network configured.");
}
}
displayAd();
```
## A/B Testing Approach
For A/B testing, modify the selection logic using:
* **Audience Segments** - Route specific user segments to different ad servers
* **Traffic Split** - Randomly assign a percentage of traffic to each ad server
Report all ad interactions (including from secondary ad servers) to Topsort to
compare metrics in one unified dashboard.
# Documentation MCP Server
Source: https://docs.topsort.com/en/api/mcp
Integrate our MCP server with your agents to become productive in no time
The **Model Context Protocol (MCP)** is an open-source standard for connecting AI applications to external systems. Topsort provides an MCP server through Mintlify that gives AI assistants direct access to our complete API documentation, enabling them to provide accurate, up-to-date information about our APIs.
Think of MCP like a USB-C port for AI applications. Just as USB-C provides a
standardized way to connect devices, MCP provides a standardized way to
connect AI applications to external data sources like our API documentation.
Looking for real-time analytics and campaign insights? Check out our [Analytics MCP Server](/api/mcp-analytics) for direct access to advertising metrics, benchmarks, and visualizations.
## What You Can Do
By connecting to Topsort's MCP server, AI assistants can:
* **Access complete API documentation** - Query endpoint details, parameters, request/response schemas, and examples
* **Get accurate integration guidance** - Receive up-to-date code examples and implementation instructions
* **Troubleshoot faster** - Quickly reference error codes, rate limits, and authentication methods
* **Stay current** - Always access the latest API documentation without manual updates
## Quick Start
Our MCP server is available at:
```
https://docs.topsort.com/mcp
```
The MCP server is publicly accessible and doesn't require authentication. However, you'll need API keys to actually use the Topsort API in your applications.
## Integration Guides
Use MCP with GitHub Copilot in Visual Studio Code
Connect ChatGPT to access Topsort documentation
Configure Claude Desktop for local development
Cursor, Windsurf, Continue, and more
## VS Code with GitHub Copilot
GitHub Copilot supports MCP servers in both the coding agent and the chat interface.
### Prerequisites
* **VS Code** version 1.95.0 or later
* **GitHub Copilot** extension installed and activated
* **GitHub Copilot Chat** extension installed
### Configuration
Press `Cmd+,` (Mac) or `Ctrl+,` (Windows/Linux) to open Settings.
Search for "MCP" in the settings search bar, or navigate to **Extensions** > **GitHub Copilot** > **MCP**.
Click **Edit in settings.json** and add:
```json theme={null}
{
"github.copilot.chat.mcp.servers": {
"topsort": {
"type": "http",
"url": "https://docs.topsort.com/mcp"
}
}
}
```
Press `Cmd+Shift+P` (Mac) or `Ctrl+Shift+P` (Windows/Linux), type "Developer: Reload Window" and press Enter.
## ChatGPT
ChatGPT supports remote MCP servers for Plus and Team subscribers.
Navigate to [chat.openai.com](https://chat.openai.com) and click your
profile icon, then select **Settings**.
Click on **Connections** or **Integrations** in the settings sidebar.
Click **Add Connection** and enter: - **Name**: `Topsort API Documentation`
* **Server URL**: `https://docs.topsort.com/mcp` - **Transport Type**:
`http`
## Claude Desktop
Claude Desktop provides comprehensive local MCP support.
### Prerequisites
* **Node.js** installed on your system (required for `mcp-remote`)
### Configuration
* **macOS**: Click **Claude** in the menu bar → **Settings**
* **Windows**: Click **File** → **Settings**
Click on the **Developer** tab in the left sidebar.
Click **Edit Config** and add:
```json theme={null}
{
"mcpServers": {
"topsort-docs": {
"command": "npx",
"args": [
"mcp-remote",
"https://docs.topsort.com/mcp"
]
}
}
}
```
Save the configuration and restart Claude Desktop.
## Other MCP Clients
### Cursor
Add to your Cursor settings:
```json theme={null}
{
"mcp": {
"servers": {
"topsort": {
"type": "http",
"url": "https://docs.topsort.com/mcp"
}
}
}
}
```
### Windsurf Editor
Configure in `~/.codeium/windsurf/mcp_config.json`:
```json theme={null}
{
"mcpServers": {
"topsort-docs": {
"command": "npx",
"args": [
"mcp-remote",
"https://docs.topsort.com/mcp"
]
}
}
}
```
Windsurf requires the `mcp-remote` package to connect to remote MCP servers. Ensure Node.js is installed on your system.
### Continue
Add to `~/.continue/config.json`:
```json theme={null}
{
"mcpServers": {
"topsort": {
"transport": {
"type": "http",
"url": "https://docs.topsort.com/mcp"
}
}
}
}
```
### Cline
Configure in `~/Documents/Cline/MCP/config.json`:
```json theme={null}
{
"topsort": {
"type": "http",
"url": "https://docs.topsort.com/mcp"
}
}
```
## Troubleshooting
### Connection Issues
* Verify the URL is correct: `https://docs.topsort.com/mcp`
* Check your internet connection
* Restart your MCP client application
* Review client-specific logs for error messages
### Server Not Responding
* Verify the transport type is set to `http`
* Check if your firewall or VPN is blocking the connection
* Check [our status page](https://status.topsort.com) for any service disruptions
While the MCP server itself doesn't require authentication, you'll still need
valid API keys to actually use the Topsort API in your applications. Never
share your API keys in conversations or commit them to version control.
## Learn More
* [Model Context Protocol Documentation](https://modelcontextprotocol.io)
* [MCP Client List](https://modelcontextprotocol.io/clients)
* [Topsort API Documentation](https://api.docs.topsort.com)
# Analytics MCP Server
Source: https://docs.topsort.com/en/api/mcp-analytics
Connect your AI agents to Topsort's advertising platform for real-time analytics and catalog operations
The **Model Context Protocol (MCP)** is an open standard for connecting AI applications to external systems—think of it as a USB-C port for AI. Our Analytics MCP server gives your AI assistants direct access to Topsort's advertising analytics and catalog APIs.
Looking for documentation access instead? Check out our [Documentation MCP Server](/api/mcp) for AI-assisted API integration guidance.
## What You Can Do
By connecting to Topsort's Analytics MCP server, AI assistants can:
* **Analyze advertising performance** - Query real-time metrics like CTR, CVR, ROAS, CPC, and ad spend across campaigns or marketplaces
* **Monitor campaign health** - Check budget utilization, bidding behavior, quality scores, and pacing in real-time
* **Compare performance over time** - Run week-over-week, month-over-month, or custom period comparisons to identify trends and anomalies
* **Benchmark against industry** - Compare campaign metrics against category benchmarks (retail, pharmacy, travel, etc.)
* **Visualize insights** - Generate line, bar, and pie charts from any analytics data for easy interpretation
* **Get Topsort guidance** - Answer questions about API integration, troubleshooting, and platform best practices
All queries can be scoped to a specific vendor, ensuring advertisers only access their own data while marketplace operators can view aggregate insights.
## Quick Start
Our Analytics MCP server is available at:
```
https://mcp-server.api.topsort.ai/mcp
```
This MCP server requires authentication. Contact your Topsort sales representative to request an API key with MCP Server access.
## Authentication
### Marketplace Authentication
All requests must include a valid API key. For MCP clients that use `mcp-remote` (like Claude Desktop), pass the key via the `--header` argument:
```json theme={null}
{
"mcpServers": {
"topsort-analytics": {
"command": "npx",
"args": [
"mcp-remote",
"https://mcp-server.api.topsort.ai/mcp",
"--header",
"X-API-Key: MPS_xxxx"
]
}
}
}
```
### Vendor ID Filtering
Tool results can be filtered for specific vendors by including the Vendor ID in the request header. This restricts the scope of all tools, preventing data leakage across vendors:
```json theme={null}
{
"mcpServers": {
"topsort-analytics": {
"command": "npx",
"args": [
"mcp-remote",
"https://mcp-server.api.topsort.ai/mcp",
"--header",
"X-API-Key: MPS_xxxx",
"--header",
"X-Vendor-Id: 1111-2222-3333-4444-55555"
]
}
}
}
```
## Tool Filtering
Tags enable fine-grained access control over which tools are available to different clients. Each tool can be annotated with one or more tags, and clients are assigned their own set of tags.
When retrieving tools, the system filters the list by checking for any overlap between the client's tags and each tool's required tags—a client only needs one matching tag to gain access.
## Integration Guides
Connect ChatGPT to Topsort analytics
Configure Claude Desktop with authentication
Test the MCP server with Postman
## ChatGPT
ChatGPT supports remote MCP servers for Plus and Team subscribers.
Navigate to [chat.openai.com](https://chat.openai.com) and click your profile icon, then select **Settings**.
Click on **Connections** or **Integrations** in the settings sidebar.
Click **Add Connection** and enter:
* **Name**: `Topsort Analytics`
* **Server URL**: `https://mcp-server.api.topsort.ai/mcp`
* **Transport Type**: `http`
* **Headers**: Add `X-API-Key` with your API key
## Claude Desktop
Claude Desktop provides comprehensive local MCP support.
### Prerequisites
* **Node.js** installed on your system (required for `mcp-remote`)
### Configuration
* **macOS**: Click **Claude** in the menu bar → **Settings**
* **Windows**: Click **File** → **Settings**
Click on the **Developer** tab in the left sidebar.
Click **Edit Config** and add:
```json theme={null}
{
"mcpServers": {
"topsort-analytics": {
"command": "npx",
"args": [
"mcp-remote",
"https://mcp-server.api.topsort.ai/mcp",
"--header",
"X-API-Key: MPS_xxxx"
]
}
}
}
```
Replace `MPS_xxxx` with your actual API key.
For vendor-scoped access, add an additional `--header` argument:
```json theme={null}
{
"mcpServers": {
"topsort-analytics": {
"command": "npx",
"args": [
"mcp-remote",
"https://mcp-server.api.topsort.ai/mcp",
"--header",
"X-API-Key: MPS_xxxx",
"--header",
"X-Vendor-Id: 1111-2222-3333-4444-55555"
]
}
}
}
```
Save the configuration and restart Claude Desktop.
## Postman
You can test the Analytics MCP server using Postman's MCP support.
Launch Postman and navigate to **Settings** → **MCP Servers**.
Click **Add Server** and configure:
* **Name**: `Topsort Analytics`
* **URL**: `https://mcp-server.api.topsort.ai/mcp`
Add the required headers:
* `X-API-Key`: Your Topsort API key
* `X-Vendor-Id`: (Optional) Vendor ID for scoped access
Click **Test Connection** to verify the server is responding correctly.
## Troubleshooting
### Connection Issues
* Verify the URL is correct: `https://mcp-server.api.topsort.ai/mcp`
* Ensure your API key is valid and has MCP Server access
* Check your internet connection
* Restart your MCP client application
### Authentication Errors
* Confirm your API key starts with `MPS_`
* Verify the `X-API-Key` header is correctly formatted
* Contact your Topsort sales representative if your key is rejected
### Server Not Responding
* Verify the transport type is set to `http`
* Check if your firewall or VPN is blocking the connection
* Check [our status page](https://status.topsort.com) for any service disruptions
## Learn More
* [Model Context Protocol Documentation](https://modelcontextprotocol.io)
* [MCP Client List](https://modelcontextprotocol.io/clients)
* [Topsort API Documentation](/api-reference)
* [Documentation MCP Server](/api/mcp) - For AI-assisted API integration
# Ad Format Configuration
Source: https://docs.topsort.com/en/knowledge-base/ad-platform/ad-format-configuration
Configure charge types, self-service access, and view campaigns for each ad format
Each ad format in Topsort has a dedicated configuration page in the **Admin
Dashboard** where marketplace operators can view campaigns, set charge types,
and control self-service vendor access — all without needing to contact an
account manager.
## Overview
Ad Format pages are available under **Ad Formats** in the Admin Dashboard
sidebar. Each page shows every campaign running for that ad format and
provides controls for charge type and self-service access.
View all campaigns for a given ad format in one place — active, paused, and
completed.
Choose how advertisers are charged: CPC, CPM, or CPA depending on the ad
format.
Control whether vendors can create campaigns for an ad format on their own,
or restrict access at the marketplace or vendor level.
Make configuration changes instantly, directly from the dashboard.
## Ad Format Pages
### Sponsored Listings
Sponsored Listings promote individual products within search results and
category pages. The configuration page supports the widest range of charge
types.
| Setting | Options |
| ----------------------- | ---------------------------------- |
| **Charge type** | CPC, CPM, or CPA |
| **Self-service access** | Enabled by default for all vendors |
### Banners
Banner ads are display creatives placed in dedicated slots across the
marketplace. Marketplace operators can restrict which vendors are allowed to
create banner campaigns through self-service.
| Setting | Options |
| ----------------------- | ----------------------------------------------------------- |
| **Charge type** | CPC or CPM |
| **Self-service access** | Restrict for the entire marketplace or by individual vendor |
### Brands
Sponsored Brands campaigns feature brand-level creatives with multiple
products. Self-service access can be restricted at the marketplace or vendor
level.
| Setting | Options |
| ----------------------- | ----------------------------------------------------------- |
| **Charge type** | CPC or CPM |
| **Self-service access** | Restrict for the entire marketplace or by individual vendor |
### Videos
Video ads allow vendors to run video creatives in designated placements.
Access controls work the same as Banners and Brands.
| Setting | Options |
| ----------------------- | ----------------------------------------------------------- |
| **Charge type** | CPC or CPM |
| **Self-service access** | Restrict for the entire marketplace or by individual vendor |
## How to Configure an Ad Format
In the Admin Dashboard sidebar, go to **Ad Formats** and select the format
you want to configure (Sponsored Listings, Banners, Brands, or Videos).
The page displays all campaigns for that ad format. Use this to understand
current campaign activity before making changes.
Select the charge type that fits your monetization strategy. Available
options depend on the ad format.
For Banners, Brands, and Videos, choose whether to allow all vendors to
create campaigns via self-service, restrict access for the entire
marketplace, or restrict access for specific vendors. Sponsored Listings
are enabled for self-service by default for all vendors.
## Charge Type Reference
| Charge Type | Description |
| ------------------------- | --------------------------------------------------------------------------------- |
| **CPC** (Cost Per Click) | Advertisers are charged each time a user clicks on the ad |
| **CPM** (Cost Per Mille) | Advertisers are charged per 1,000 impressions |
| **CPA** (Cost Per Action) | Advertisers are charged when a conversion is attributed (Sponsored Listings only) |
## Self-Service Access Reference
| Ad Format | Default | Restriction Options |
| ---------------------- | ----------------------- | ------------------------------- |
| **Sponsored Listings** | Enabled for all vendors | Not restrictable |
| **Banners** | Configurable | Entire marketplace or by vendor |
| **Brands** | Configurable | Entire marketplace or by vendor |
| **Videos** | Configurable | Entire marketplace or by vendor |
***
# Using Assets
Source: https://docs.topsort.com/en/knowledge-base/ad-platform/assets/index
Managing assets
Topsort supports many types of assets that can be used in campaigns. See below for supported asset types.
## How It Works
### Uploading Assets
While creating a campaign, you can upload assets to banner or sponsored brand campaigns. These assets can be images, videos, html or externally hosted files (a url). These assets will be returned as part of a winning auction and suitable for inclusion in the ad creative.
You can also use our [Assets API](/en/api-reference/assets-api), to create and manage assets without necessarily using them in campaigns.
### Supported Asset Types
We support the following asset types:
* **Images**: PNG, JPEG, GIF and WEBP.
* **Video**: MP4, WEBM, MOV.
* **External URL** (can be anything you want to use from a third party service)
* **HTML**: HTML code that can be used to render a custom creative. We return the link to said HTML file which you can include via an `
Product Title