This is the alternative method for integrating your catalog instead of passing the product feed. The benefit of using the catalog API is to support a large inventory system and making sure the products are always in sync regarding availability and related product information. If you would like a speedy integration or your marketplace does not have a large volume of inventory fluctuation, we recommend using the Product Feed to pass the catalog.
The Catalog API lets you add, modify and delete the different catalog entities that Topsort will use during the campaign creation flows. For your sandbox, all catalog API requests should be sent to https://central-services.api.sandbox.topsort.ai/public/.
Currently, our catalog stores 3 types of entities:
- Categories — A category in Topsort's model is essentially a group to which a product may or may not belong to. This model serves as a way to search and filter out products during the campaign creation process.
- Products — The definition of a product may vary depending on the context. Topsort defines a product as something being sold in a marketplace which needs to be individualized via a unique product identifier. Products are the main component of catalogs, all other catalog models exist to group or enrich these products.
- Vendors — A vendor, for the purpose of the catalog API, is an entity selling products within a marketplace. A vendor might sell products from different brands and categories. A vendor is usually the main administrator of its own products, campaigns and ads.
For each of these entities, we provide 4 endpoints:
- Upsert: you can create or update multiple entities at once (e.g. update a product and create 2 new ones). Each entity is identified by a unique ID. If there was no ID for an entity you've sent, it will get created; otherwise, we will update the existing entity.
- Fetch: you can fetch all entities you've added into Topsort. The results are paginated, so you may need to scroll through multiple pages of results to find them all.
- Fetch (with ID): you can also fetch a specific entity if you provide its ID. We will send you back what you've stored in Topsort, or warn you if we don't have such an entity.
- Delete: you can also delete any entities you no longer have in your catalog. Depending on the case, we might still keep some of this data so existing campaigns associated with these entities don't break. To delete a set of entities, you'll need to send us their IDs.
We're here for support
If you need help implementing this service, please contact us. We can provide you with the needed scaffolding for your language or framework.