API Reference

Overview

How it works:

You can get up and running with Spresso in 3 easy steps:

  1. Send us your current catalog. You can log into our console and upload a CSV file.
  2. Install our SDK on your website and mobile apps and configure your storefront to send us event data. We feed information about product impressions and conversions to our AI models so that they can select the best price for your items.
  3. Wherever pricing is displayed on your platform, replace your static prices with the AI-driven pricing generated by Spresso. Our system continually monitors the performance of every item in your catalog and adjusts prices accordingly.

Technical Details:

Catalog Intake:

You can follow the instructions here to deliver catalog information to our systems: https://spresso.readme.io/docs/manage-your-catalog.

Event SDK:

There are 6 events that we need to track in order to provide enough information to our systems - these are industry standard, and follow the same patterns as most other ecommerce conversion tracking tooling. In fact, if you already track these events, you can just use a data connector to pipe this data straight to our systems without needing the SDK.

Instructions for our Web, iOS and Android SDKs can be found here:

https://spressoinsights.github.io/spresso-sdk-tracking-web/index.html

You need an organization ID for our SDK and can obtain it from our console - please be mindful of using only using your production organization ID in your production environment so that the Spresso machine learning algorithms do not get biased toward your test data.

Price Optimization API:

There are two options for accessing our pricing API: one returns the pricing for a single SKU and one takes a group of SKUs and returns pricing for all of them. Documentation for both can be found here: https://spresso.readme.io/reference/get_v1-priceoptimizations

Our pricing API can be used to inject dynamic prices on the frontend OR server-side. Regardless of where you choose to inject Spresso prices, you will need an authorization token before you can successfully obtain a price.

The recommended process is as follows:

  1. Obtain a client ID and secret for your organization from our console.
  2. The secret you receive must be stored securely on your servers and never deployed or released to your frontend code.
  3. To get an access token use our token API here: https://spresso.readme.io/reference/post_v1-public-token
    1. NOTE: The audience parameter is always https://spresso-api and the grant_type always client_credentials
  4. The token you get back will be a signed JWT token that can be cached for 24 hours and must be used with all subsequent requests to our price optimization API. We always suggest accessing the Spresso price optimization API through your backend - regardless of where prices are injected.
  5. You can choose two options to inject prices:
    1. When your frontend requests a product or list of products, call the Spresso API before returning the products and inject the dynamic prices into the response sent back to the browser.
    2. If you are unable to inject prices server-side, when a product (or products) is loaded into your front-end, defer rendering of the HTML until you’re able to access the relevant Spresso API. Our API’s are designed to have very low latency so the extra loading time should not be apparent to a user.
  6. Regardless of where you choose to inject prices, we always recommending injecting prices AFTER filtering results from your catalog, so you only need to update pricing for the subset of items which will be displayed to the user.
  7. The requests you make to our price optimization API contain a few important configuration parameters:
    1. defaultPrice: a fall-back price you must provide in case of errors communicating with our API or if the item is not in our catalog.
    2. overrideToDefaultPrice: a boolean value you can use to coerce our API to always return the defaultPrice provided above. See use cases for this parameter below.
  8. The responses contain the dynamically generated price, as well as a TTL parameter in milliseconds which you can use to cache prices to improve latency even further.
  9. There are instances where for certain user agents you will NOT want to use dynamic pricing. Some marketplaces such as Google Marketplace require stable pricing. We maintain a list of known user agents which can be accessed via our API. When a bot presents a user-agent for a known bot, present the default price. The Spresso SDKs will automatically do this for you.

When should I use overrideToDefaultPrice=true?

  • If you detect that the user agent is a bot, set the catalog price as the defaultPrice and enable the overrideToDefaultPrice flag.
  • If you have pre-negotiated prices for a given user or set of users, set the defaultPrice to the pre-negotiated pricing, and enable the overrideToDefaultPrice flag.
  • If you have special promotional pricing for a given sku, set the defaultPrice to the promo price and enable the overrideToDefaultPrice flag.
  • If you have a loyalty program that mandates a certain price for a group of users, set the defaultPrice to the loyalty program price, and enable the overrideToDefaultPrice flag.