Catalog API
Topsort’s Catalog API will allow you to sync with Topsort’s the items that are going to be promoted by the advertisers. Our catalog is flexible enough to support different industries, such as retailers, travel agencies, finance institutions, among others. Customers can model their business to represent exactly what they are selling on their platform. Please note that Products and Categories are not required to run banner campaigns.
To run auctions with the catalog items, Topsort needs at least the Product ID, Name, one Category and one Vendor. The Catalog API stores 3 entity types:
- Products: Items promoted in a marketplace with unique identifiers.
- Categories: Groups for products, helping with search and filtering.
- Vendors: Entities selling products across various brands and categories.
Each entity type has 4 endpoints:
- Upsert: Create or update multiple entities simultaneously.
- Fetch: Retrieve all entities added to Topsort (paginated).
- Fetch (with ID): Retrieve a specific entity using its ID.
- Delete: Remove entities from the catalog, requiring their IDs.
Products
A product is the item that will be promoted. It could be a physical item, a service, or a promo code, whatever makes sense for your use case. For example, in the diagram below, a catalog has physical products (shoes in this case). The sneakers in this catalog are promoted in a sneaker campaign.
Whatever your product is, it must have a unique ID for tracking and targeting purposes. We treat IDs as opaque strings. This unique ID doesn’t need to be an SKU, it just need to be a consistent unique identifier. For example:
- Restaurant ID for delivery apps
- Hotel ID for a travel platform
- Flight ID for an airline
Variants
Some products come in variants, such as:
- Small green t-shirt
- Medium yellow t-shirt
- Large blue t-shirt
Depending on your retail media strategy, you might need to promote at variant level, or grouping variants together. Define your product hierarchy based on what vendors will be able to promote.
Required and Optional Fields
-
A product must have:
- id: Unique identifier (string)
- name: Shown in Topsort UI
- category: At least one category
- vendor: At least one vendor
-
You can also include additional data to improve reporting:
- EAN code
- Description
- Brand
- Image
- Price
Categories
Categories help you organize the catalog and define how products will be grouped. Auctions can also target specific categories or groups of categories.
Each product must belong to at least one category. A single category can include multiple products, and a product can be assigned to multiple categories if needed. For example, a product like SKU-547 might belong to both CAT-1 and CAT-3.
Each category can be structured hierarchically, each category having a parent, allowing for the creation of nested structures.
Vendors
A vendor represents a business or brand that promotes their products using campaigns. These campaigns can be managed by the administrator of the marketplace, or directly using our self-service dashboard.
Each product of the catalog must have at least one vendor, while the same product can have multiple vendors. Vendors can only promote items they have assigned to themselves in the catalog.
Example:
- SKU-789: Only promoted by VENDOR-1
- SKU-791: Only promoted by VENDOR-2
- SKU-790: Can be promoted by both VENDOR-1 and VENDOR-2