Skip to main content

Syncing your Catalog

Relevant API endpoints

There are 2 prerequisites before you can start showing topi prices on your ecom store and using topi for checkout:

  1. Syncing your catalog (this article)
  2. Setting up shipping methods (next article)

Let's start by understanding why topi needs your catalog.

Why topi needs your catalog​

Every ecommerce store has an underlying catalog that contains the collection of products for sale. Your store's catalog always remains the source of truth for prices, inventory availability, variants, descriptions, etc.

Unlike simple payment solutions like PayPal or Klarna, topi needs your catalog so that we are able to compute (and refresh) our rental prices, available rental tenures, and other services based on your products' type, price, and other attributes.

What topi needs to ingest your catalog​

If you send us your product catalog, we can easily convert all of your purchase prices into monthly prices so you can offer your products as a subscription at affordable monthly rates.

What information do we need from you?​

  1. Product name/title
  2. Indicate whether its a service, software, hardware, or custom-to-order hardware
  3. Seller product reference
    1. Source (Typically, this field should be filled with the name of your ERP system, for example, SAP.)
    2. Reference (Typically, this field should be filled with the article number)
  4. The purchase price
    1. Gross
    2. Net
    3. Currency
  5. If it’s a service we need the following:
    1. Who offers the service (e.g. Seller vs OEM)
    2. Type of service (e.g. support, warranty, extension services, MDM, staging, setup, training, software)
    3. Tenure of the service
    4. Payment type (e.g. one-off vs recurring)
    5. What Seller product reference number the service corresponds to
    6. Whether the service is a standalone Seller product reference number or included in a custom-to-order device

You may also include additional fields, if your catalog includes this information:

  1. Subtitle
  2. Description of product
  3. Product Standard Identifier
  4. Manufacturer

To see all the extra information you can add, please see /catalog/import.

How can you provide this information to topi?​

There are two ways to provide this information - manually or and automatically via API

  1. Manual Process: All we need from you is a CSV or an XLSX file with the information above, and we will ingest it into our system. Please note that performing this task manually means that any changes to the information, such as product additions or modifications, pricing adjustments, etc., will not be reflected. Whenever there is a change, please reach out to us with this information. Here is an example CSV.

  2. Automatic Process: All we need from you is a JSON file containing the information above, which we can ingest via an API call. Please see the /catalog/import. Although this method requires some integration effort on your part, it ensures that any changes made to your catalog will be automatically reflected on our end. There is little to no maintenance required! You can count on us to always have up-to-date information. For API Reference, see /catalog/check-supported.

Syncing for the first time​

Depending on the size of your catalog, whether it's in the hundreds or millions of products, the first sync may take longer to complete on topi's end.

For small catalogs, this is likely to take only a few minutes. For larger catalogs in the order of tens or hundreds of thousands of products, it may take up to a few hours.

You can make test GET calls to the Catalog API to see which products have been synced to topi and are ready for renting.

Syncing regularly over time​

Once the initial sync has completed, you can expect future syncs to complete faster as topi will run a diffing algorithm to ensure only products with changed details will be updated in our database.

We recommend using the Catalog import endpoint to periodically upload your latest catalog in full to topi.

Frequently Asked Questions (FAQs)​

What happens when I remove products?​

In short, nothing happens. Currently topi never deletes products that have been synced. Instead, topi upserts (update or insert) products that you send over.

For example, if upload_A contained 100 products, and upload_B (sent some time later) contains only 99 products, the removed product will simply stay in the catalog on topi. Assuming that the other 99 products were already present in uploadA, then uploadB will just cause topi to update the details of those existing products in your catalog.

My catalog size exceeds the HTTP request size limit on topi's server. What can I do?​

This happens! To get around this problem, you'll need to chunk your requests to topi. If you have 10,000 items, try sending them as 10 requests with 1,000 items each.

Does topi have plugins for syncing catalogs?​

Yes, currently we support syncing to topi via the Shopware plugin.

Shopware 5 plugin is not available via the Shopware store but is available on request. Reach out to your topi point of contact if your ecommerce store is built on Shopware 5.

What happens if I don't have an ecom store?​

Fret not! If you do not have your own ecommerce store, you can make use of a "central catalog" provided by topi to get started. You can then create offers out of our topi Tool for telesales and in_store_pos (point of sales) sales channels.

For more information, please reach out to your topi point of contact.

Next, let's setup our shipping methods.