Guides

Custom Platform Install Instructions

Suggest Edits

Background

Spresso Price Optimization is a plug and play solution to provide dynamic pricing functionality to every item in your catalog. Using our proprietary AI, we can fine tune pricing on a per-SKU basis to maximize gross margin OR conversion rates based on your priorities.

How it works

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

  1. Send us your current catalog. The preferred method of delivery is a nightly SFTP upload - just like you would to any other ad / affiliate network. NOTE: If you use BigCommerce, Shopify or VTEX to power your e-commerce backend, this will be taken care of automatically for you via our integrations on those platforms.
  2. Install our JS SDK on your e-commerce store.
  3. Wherever pricing is displayed on your store, replace your static prices with Spresso DOM markers. Once you've done that, use our Add to Cart helper to ensure the price a user sees in their cart matches the price they encounter while browsing your site.

Technical Details

Catalog Intake

Timely and up to data catalog information is a core component of fueling Spresso's AI model.

👉

Refer to catalog guide here for details and methods.

Remember, for an off-the-shelf e-commerce backend, our system will be able to handle this automatically for you


JS SDK

Simply add the Spresso snippet below to the <head> of your HTML. If you install any of our apps, you can skip this step.

<script
    defer
    src='https://api.spresso.com/sdk/latest/spresso-web-sdk.js?id=<YOUR ORG ID>&currency=USD'
>
</script>

NOTE: You can find your organization ID by logging in to our console. If you use one of our apps, the SDK is automatically installed for you!

For a headless build with an off-the-shelf e-commece backend, we have special builds of our SDK you should include. For example, if you use a Shopify backend, please modify the snippet above as follows:

<script
    defer
    src='https://api.spresso.com/sdk/latest/shopify-sdk.js?id=<YOUR ORG ID>&vendorStoreName=<YOUR MYSHOPIFY DOMAIN>&vendorApiKey=<SF ACCESS TOKEN>&currency=USD'
>
</script>

Displaying Dynamic Pricing with DOM markers

In order to ensure that Spresso’s AI-generated prices are displayed, replace your static pricing from the HTML and replace it with markers that tell Spresso’s SDK what price to inject. The Spresso JS code registers a mutation observer which searches the DOM for any Spresso data attributes. When it finds the data attribute, it will replace the content of that element, if blank, with an AI-generated price from Spresso’s system. If the element is not blank, Spresso will leave the contents unchanged.


Original HTML:
<span class="price-display">{price}</span>

Spresso-compatible HTML:

<span  
      class="price-display"  
      data-spresso-item-id=”SKU-123”  
      data-spresso-item-type=”product-sku”  
      data-spresso-pricing-display=”range”  
      data-spresso-fallback-id=”987123”
>
  &nbsp;&nbsp;&nbsp;&nbsp&nbsp;
</span>

NOTE: The reason we use multiple spaces (&nbsp; ) above is to ensure that when the price is injected by Spresso’s system, the DOM element retains its width and does not get resized.


Description of DOM markers:
data-spresso-item-id: The identifier Spresso uses to determine which item’s price to inject. You can use any unique identifier, provided you send us the entire list of identifiers when delivering your catalog.

data-spresso-item-type: The type of the identifier provided, available options are variant-sku (default), product-sku, variant-id (the variant primary key in your system), product-id (the product primary key in your system) or a custom identifier type you create during catalog intake.

data-spresso-pricing-display: If the identifier type above is product-sku or product-id, the display attribute must be provided. This allows Spresso to determine how to display pricing for the product. The available options are min, max and range. Min will display the price of the lowest-cost variant of this product, Max displays the price of the highest-cost variant and range displays both min and max prices, separated by “ - ”

data-spresso-fallback-id: The primary key for this item in your e-commerce system. This is used in scenarios where a price from Spresso’s API is unavailable for any reason (ex: catalog intake not completed). Since you are removing all prices from your HTML, if Spresso’s API cannot return a price for this item, we use the fallback identifier to fetch the catalog price via your e-commerce vendor's API and display that instead so that an end user always sees a price where one should be displayed.

data-spresso-price-context: Indicates to the Spresso AI system the part of your site on which the price is being displayed. Available options are gallery (default) and pdp. Any location where the product is displayed as part of a list, i.e. ad-hoc carousel, personalized gallery etc should all use gallery or not add this attribute, pdp should be used only for the main item on a PDP page.

data-spresso-oos: Indicates to the Spresso AI system that the particular product is Out Of Stock. This changes how we weight a user's browsing activity for that product because any browsing sessions with an out of stock item would never result in a purchase.

Please reach out to the Spresso team to set up time with a sales engineer discuss integration options and to better understand your unique store setup and any customizations you may have already made


Adding to cart:

When an item is added to the cart, you have to invoke Spresso's ATC method to make sure the Spresso price is reflected in the user's cart and not the default price from your Database (also called the catalog price).

Under the hood, we implement the correct API for your e-commerce vendor to ensure the cart is updated correctly. Please note that this requires a network request, so you must wait for this request to complete before displaying a cart preview UI. You can do this using the standard await syntax in JavaScript. An example of the correct usage is shown below:

await window.Spresso.handleAddToCart({
  itemId: 'xyz-001',
  itemType: 'variant-sku',
  quantity: 1,
  ... // also add any custom parameters needed for a specific vendor's API
});

For a headless build with an off-the-shelf e-commece backend, we have special versions of the handleAddToCart you should use. For example, if you use a Shopify backend, please modify the snippet above as shown below:

// In your add to cart handler
const newAttributes = (
  attributes && attributes.length ? attributes : []
) as AttributeInput[];

try {
  // Adds the spresso attributes to the attributes array
  await window.Spresso.addSpressoCartAttributes(legacyId, newAttributes);
} catch (ignored) {}

Manipulating the Spresso Price

If you need to utilize a number derived from the Spresso price use the following DOM attribute:

data-spresso-transform followed by a series of | separated transform rules that are applied to the Spresso AI-generated price. The AI-price is represented by the variable named price.

Available operators:

abs: Returns the absolute value of a number.
at_least: Limits a number to a minimum value.
at_most: Limits a number to a maximum value.
ceil: Rounds a number up to the nearest integer.

divided_by: Divides a number by a given number. The divided_by rule produces a result of the same type as the divisor. This means if you divide by an integer, the result will be an integer, and if you divide by a float, the result will be a float. The integer division follows Python-style rules.

floor: Rounds a number down to the nearest integer.
minus: Subtracts a given number from another number.
modulo: Returns the remainder of dividing a number by a given number.
plus: Adds two numbers.
prefix: Prepends text to the number. After this, you cannot perform any further math.
round: Rounds a number to the nearest integer, add an argument to specify number of decimal places.
suffix: Appends text to the number. After this, you cannot perform any further math.
times: Multiplies a number by a given number.
to_string: Formats the value as a localized currency string. After this, you cannot perform any further math.
to_intl: Formats the value as a localized number. This will include locale-specific commas and also ensure that if the number is a whole number no .00 is rendered after.

Example Usage

  1. Display a 20% off price for a subscription purchase:

data-spresso-transform="price | times: 0.8 | round: 2 | to_string | prefix: Subscribe and Save price:"

Given a Spresso price of $50, this will display Subscribe and save price: $40.00


  1. Display a 10% loyalty points tally for an item

data-spresso-transform="price | divided_by: 10.0 | round | prefix: Loyalty Points Earned:"

Given a Spresso price of $50, this will display Loyalty Points Earned: 5


NOTE: The manipulated price above is only used for display - if you need it stored as a DOM attribute, you can use the data-spresso-target-attribute value to specify which attribute to save the value to, and Spresso will append that attribute with the correct price to the DOM.

Updated 6 days ago