Displaying topi prices
We have developed topi Elements, a small JavaScript UI library, to do the heavy lifting of displaying prices and other UI elements on your shop. It's free to use and continually updated. Have a look!
What are topi prices?
topi prices refer to the prices for renting a product over a period of time.
Let's take an example of a basic MacBook Pro, which costs €2400 to purchase. This product might have the following topi prices:
- €167.99 per month for 12 months
- €86.49 per month for 24 months
- €58.99 per month for 36 months
(note: these prices are for illustrative purposes only.)
Net vs Gross prices
If you take a look at the Catalog API reference, you'll notice that topi returns both net and gross prices in the response. We've designed the response this way to accommodate to the different preferences of our sellers.
In Germany's business-to-business (B2B) world, prices are always net, and in the business-to-consumer (B2C) world, prices are always gross.
Net = price excluding taxes. Gross = price including taxes.
We recommend showing net prices as topi operates in the B2B world, but as we've alluded to, the choice is yours!
Passing the optional price value
You have the option of passing or not passing a price attribute when calling topi's Catalog endpoints.
When you pass a price attribute when requesting rental prices, topi will ignore the product's catalog price for that response, and use the passed-in price for calculating topi rental prices.
Note: topi will not override the catalog's price based on your requests. To update prices on your catalog, you'll need to upload your catalog with the latest prices to topi.
When you omit a price attribute, and pass only the mandatory seller_product_reference attribute, then topi will use the catalog's price for that product to calculate topi rental prices.
On the Product Detail page (PDP)
To obtain prices for single products, use the listRecommendedRentalPrices endpoint.
The response payload will give you an indication of whether the product can be rented via topi, what the monthly price would be for 6, 12, 24, 36 months rent tenures and what the one-off pay_now price would be if customers choose to buy instead of rent. It will also contain a summary string like "Rent with topi for €58.99/month".
With this pricing info, you can then render the topi price on the PDP according to your preference.
Our recommendation: on the PDP, we recommend rendering the possibility to rent via topi by showing a topi logo and the lowest rental price. You can use the has_rental_terms boolean to conditionally render this, and the lowest rental price is included in the summary string.
On the Product Listing page (PLP)
Similar to PDP, to obtain prices for a list of products, use the listRecommendedRentalPrices endpoint. This endpoint takes in an array.
With this pricing info, you can then render the topi price on the PLP according to your preference.
Our recommendation: on the PLP, we currently recommend rendering the same details as on the PDP.
On the Cart page
We will walk through how to display prices on the Cart page later in Adding a Checkout button, because on the Cart page, you will also need to conditionally render a checkout button, for which you have various options.
Frequently Asked Questions (FAQ)
How do I ensure topi has my latest product prices?
Two mechanisms are in place to ensure topi provides accurate rental prices all the time:
- Regular catalog uploads
- Passing
pricewhen creating a topi offer
We recommend ensuring that you have setup a periodic upload of your catalog to topi. This way, topi always works on your latest product prices across your catalog.
We also recommend, wherever possible, to pass in price information when creating an offer, even though that field is optional (see Passing the optional price value). This way, you'll ensure that topi is using the latest price at the moment of checkout.
If you do these two things, topi will always provide you with accurate rental prices.
Do product prices change in a topi offer?
Once a topi offer is created, the rental and "buy now" prices in that offer are frozen until the offer expires.
We designed a topi offer this way to support the way B2B sales works.
For instance, if a customer requires additional time to decide on a large purchase after receiving an offer, they will be able to return to an offer with the pre-agreed prices. This ensures that the customer's initial price observation is maintained throughout the decision-making process.
Can I still use the calculatePricing endpoint?
The calculatePricing endpoint has been deprecated and is only meant to support existing integrations. It has been replaced by the more ergonomic and efficient listRecommendedRentalPrices endpoint, which we recommend you to use instead.
With topi prices showing on your ecommece store on the PDP and PLP, we can now add a "Rent with topi" button into your checkout flow.