Knowledge Base

Catalog Syncrhonization

To effectively participate in Topsort’s auction-based ad system for sponsored listings or sponsored brands, integrating your product catalog is the first crucial step.

Topsort needs access to product data to run smooth auctions and promote products. Most importantly, we require productID, category, and vendor information of products.

If you already have a standard product feed that you send to Meta or Google, we can easily load it into the sandbox for you.

Catalog API is an alternative method to connect large quantities of products in real-time, only recommended for classified marketplaces with non standard catalog or large volume of catalog (above 100 million SKUs).

Topsort supports multiple methods for syncing product catalogs, offering flexibility in data transfer. Retailers can upload catalog files daily via CSV or TSV formats through an authenticated URL, SFTP, or S3 bucket. For more dynamic updates, Topsort provides a push API that allows real-time modifications such as stock availability changes or new product additions.

Recommendations

For sandbox environments we can use a CSV/TSV/Product Feed file which allows the retailer to test the platform in minutes.

In production, the recommended approach is a hybrid model: daily full catalog updates combined with API/file-based updates for smaller changes.

The retailer should enable a URL (with authentication) where Topsort can fetch the whole catalog from. This process should run daily.

Additionally, if the retailer wants to send update changes like new products, or availability changes with higher frequency, it is recommended to do it using the API for real-time changes or with a file.

The structure of the full catalog file and the availability file can be different and Topsort will take care of mapping each file’s structure to Topsort’s form.

On availability, the recommendation is for the client to manage product availability per location/store on their side and send only available candidates in the auction request, considering user context.

Topsort can handle parent product IDs or variations SKUs. While variations provide more flexibility to advertisers, Topsort’s recommendation is to use parent product IDs to minimize availability issues, and to improve ML models prediction.

References

Protocols

External URL: Supports S3 or any hosting with simple authentication (user/password or bearer token)..
SFTP: Client or Topsort can configure the SFTP server. Client provides documentation, sample files, and naming conventions. Topsort handles automated checks, error handling, data transformation, loading, monitoring, and maintenance.
Monitoring and Alerts will run on Topsort’s side.

Using the API

Availability

Retailers can provide availability data separately from the full product catalog. This data can be synchronized at different frequencies, such as hourly or multiple times per day. Availability data follows a lightweight schema, typically including Product ID, Store Location, and Stock Status (active: true/false), minimizing file size while maximizing ad accuracy. This feature enables more context-aware ad serving, improving the user experience and conversion rates by preventing failed checkouts due to unavailable products.