Koru Calculator Widget

Product calculator for VTEX product pages. The shopper enters a measurement and the widget resolves how many units are needed, validates real price and stock, and adds them to the cart.

Koru Calculator Widget is a VTEX IO app declared as a theme block on the product page. It solves the case of products that are sold by unit but consumed by measurement: paint that covers 10 m² per can, feed sold in 20 kg bags, fencing supplied in 10 m rolls.

The shopper enters the measurement they need — m², meters, kg, m³, or units — and the widget computes ceil(measurement / yield), reads real price and stock from the VTEX Catalog, displays the total, and adds the item to the native cart with the exact quantity.

Before you start

Recommended owners

A single person may cover several roles in a small store.

Required access

Before installing, confirm that you have:

• A valid VTEX Admin session in the store account.
• The official VTEX CLI, installed and up to date.
• Permission to install apps and link the theme in the chosen workspace.
• Access to Catalog → Specifications to create and assign the yield and unit fields.
• The store's Website ID in Koru Suite, with Koru Calculator Widget active for that website.

The app does not request or store merchant credentials: the backend uses the app's own authToken to reach the Catalog. No AppKey/AppToken is required.

Credentials and identifiers

Installation

This app is installed only as a VTEX IO theme dependency (Store Framework). There is no <script> or Google Tag Manager version.

vtex login {store-account}
vtex use {workspace} --create
vtex whoami                                  # verify account and workspace before continuing
vtex install soluciones4fpartnerar.calculator-widget@0.x
vtex list                                    # confirm it appears in the list

{
  "dependencies": {
    "soluciones4fpartnerar.calculator-widget": "0.x"
  }
}

{
  "flex-layout.col#details-column": {
    "children": [
      "vtex.store-components:product-name",
      "flex-layout.row#product-prices",
      "calculator-widget",
      "flex-basic#buy-button"
    ]
  },
 
  "calculator-widget": {
    "props": {
      "title": "Calculate how much you need",
      "ctaText": "Add to cart",
      "websiteId": "YOUR-WEBSITE-ID"
    }
  }
}

Multiple instances in the same store

The block supports the standard VTEX #id instance pattern, for example to render a variant elsewhere on the product page:

{
  "calculator-widget#compact": {
    "props": {
      "title": "Quick calculator",
      "websiteId": "YOUR-WEBSITE-ID",
      "blockClass": "compact"
    }
  }
}

• Each instance needs its own websiteId: the prop is not inherited between instances.
• The block does not set its own position — it renders wherever you place it in the block tree. Because it needs product context, every instance must live on the product page.

Visual customization with CSS

Default styles come from Tachyons with VTEX design tokens (t-heading-5, c-on-base, bg-action-primary, b--muted-4), so the widget automatically inherits the account's colors, typography, and button style. The app's .css files do not hardcode colors.

Every element also exposes a CSS handle. The theme override file is:

styles/css/soluciones4fpartnerar.calculator-widget.css

.cta {
  border-radius: 0;
  text-transform: uppercase;
}
 
.stockAlert {
  font-weight: 600;
}

Available handles:

Updating and uninstalling

Select the correct account/workspace, confirm it, and install the range again:

vtex whoami
vtex install soluciones4fpartnerar.calculator-widget@0.x
vtex list

Uninstalling applies to the current workspace:

vtex uninstall soluciones4fpartnerar.calculator-widget

The websiteId lives in the theme block configuration, not in app settings: if you uninstall and reinstall the app, the prop remains in the theme.

Activation in Koru Suite

The app is license-gated. If the website and the app are not active in Koru, the widget is replaced by the notice "Widget no disponible — Esta aplicación no está habilitada para este sitio. Comuníquese con Korusuite."

The gate runs client-side from the shopper's browser. No Koru login or VTEX Admin session is involved: the only thing validated is that the Website ID + App ID pair is authorized.

Configuration

Configuration is split across three places, and none of them is Koru:

1. Block props — titles and license.
2. VTEX catalog specifications — which formula each product uses and how much it yields. This is where the logic lives.
3. Theme CSS — appearance (see Installation).

Block props

Catalog specifications

Create two specification fields in VTEX Admin (Catalog → Specifications, or from the category's specification group) and assign them to the categories where the widget runs. The app looks them up by exact name, trying the candidates in order:

Rules to keep in mind:

• The field name is what matters, not the specification group.
• The yield must be a number greater than 0. Empty, 0, or non-numeric values are ignored and the cascade continues.
• The unit is read from the product, not the SKU, and is used for two things: choosing the formula and displaying Rendimiento X <unidad> c/u in the summary.

Unit of measurement → active formula

The value of UnidadMedida determines which formula the widget uses and which fields the shopper is asked for:

perimetro is not mapped to any unit. Since the block cannot pin a formula, the only way to offer it is to leave the product with an empty or unrecognized unit: all 7 formulas are then listed and the shopper chooses.

Accepted aliases (case, spaces, accents, and periods are normalized):

Any other value counts as "unrecognized" and all 7 formulas are offered. Recommendation: always load the short form (kg, m2, m, m3, un).

Available formulas

Formulas are not editable from any panel: they live in the app code. Adding or changing one requires publishing a new app version. The client never sends the expression: it sends a formulaId that the backend validates against the whitelist, and evaluation runs in restricted mode (no eval, no new Function, no function definitions or assignments).

How the calculation works

Yield cascade

The yield is resolved server-side, taking the first valid value (greater than 0) in this sequence:

Final calculation

gross          = expression(shopper inputs)
final_quantity = max(0, ceil(gross / yield))
total_price    = unit_price * final_quantity
stock_alert    = final_quantity > available_stock

precio_unitario and stock_disponible come from the Catalog's public search (Price and AvailableQuantity of the SKU's first seller). If the SKU has no offer, both return 0.

Backend endpoint

The block calls this endpoint with a 300 ms debounce whenever the inputs, the selected SKU, or the chosen formula change, and cancels the previous request. Nothing is recalculated on the client: it only renders the response.

What happens when adding to the cart

Recommended setup order

Data and privacy

• The app has no storage of its own: no Master Data, no VBase.
• The only persisted data is the OrderForm customData with the values entered by the shopper, for order traceability.
• The browser stores the license cache in localStorage under the key koru_widget_<WEBSITE_ID>_<APP_ID>, for 300 seconds.
• No merchant credentials are requested or stored. There are no Koru secrets in the browser.
• The calculation endpoint responds with no-store and does not record personal data: it receives measurements, not shopper identity.

Functional limits

The current version:

• Requires product context: it works only on the product page.
• Does not allow pinning the formula or the yield from the block or the Site Editor.
• Does not allow creating or editing formulas without publishing a new app version.
• Adds the item with a single seller: it is not designed for multi-seller or marketplace stores.
• Reads price and stock from the sales channel resolved by the public search. In stores with multiple sales channels or trade-policy pricing, the displayed price may not match the shopper's policy.
• Shows the stock alert as a visual warning, without blocking the purchase.
• Ships its internal copy in Spanish; it is not translatable from the theme.
• Has no <script> or Google Tag Manager version.

Troubleshooting

The app was activated in Koru but the "Comuníquese con Korusuite" notice remains

Negative responses are not cached, so a Koru activation takes effect on the next page load. What is cached is the positive response, for 300 seconds (5 min), in localStorage under the key koru_widget_<WEBSITE_ID>_<APP_ID>. To force it: delete that key from localStorage or wait 5 minutes.

If the notice persists, verify that the block's websiteId matches Koru exactly (no spaces) and that the app is enabled for that website.

The widget does not appear at all — neither the calculator nor the error notice

In this order:

1. Product context: the block must live inside store.product. Without a SKU in the product-context, the component renders nothing.
2. Theme dependency: the app must be in the theme's manifest.json, and vtex link restarted after adding it.
3. Block name: calculator-widget, or soluciones4fpartnerar.calculator-widget:calculator-widget if the theme uses full prefixes.
4. Backend logs:

vtex logs soluciones4fpartnerar.calculator-widget

I changed UnidadMedida or the yield and the widget did not notice

UnidadMedida and the product-level yield reach the storefront through the search index: the change is not instant, you must wait for the Catalog reindex and hard-refresh the product page. You can verify the current value at:

https://{account}.vtexcommercestable.com.br/api/catalog_system/pub/products/search/?fq=productId:{id}

A yield loaded at SKU level is read through the private Catalog and applies immediately.

It asks for fields that do not match the product

For example, width and height on a product sold by kg: UnidadMedida is empty, misspelled, or outside the accepted aliases. Load kg, m2, m, m3, or un.

A selector with 7 formulas appears

That is the expected behavior when the unit is not recognized. Load a valid unit if you want the widget to choose on its own. Conversely, if you need to offer perimetro, this is the only way.

The calculated quantity equals the entered measurement

As if the product yielded 1: the yield specification is missing, or its value is 0, non-numeric, or uses a comma instead of a period. Load ValorRendimiento greater than 0 on the product or the SKU.

The yield does not change when switching variation

It is loaded at product level. To make it vary per variation, load it at SKU level: the widget resends the selected skuId and recalculates on its own.

Total price is 0 and stock is 0

The SKU has no offer/price in the sales channel returned by the public search. Review the SKU's price and availability. As a side effect, with stock 0 the stock alert always shows.

It says "Stock insuficiente" but still allows adding to the cart

This is intentional: the stock alert is a visual warning. The button is disabled only when the calculated quantity is 0 or while the item is being added.

The shopper leaves a field empty or types text

While any formula field is missing, the backend is not called and there is no result. Non-numeric values are discarded on the server; if that leaves a formula variable without a value, the widget shows "No se pudo calcular. Revisá los valores e intentá de nuevo.".

Inputs are numeric with min=0, but the backend does not reject negatives: it accepts any finite number and then clamps the final quantity with max(0, …).

Does it affect site performance?

The widget is fully client-side when loading: it does not block product page rendering, but it makes two kinds of request from the browser.

1. The license gate: one fetch to korusuite.com per page load, unless a valid 5-minute cache exists. While it responds, the widget area shows "Verificando disponibilidad…".
2. The calculation: one same-origin POST to the app backend per input change, with a 300 ms debounce and cancellation of the previous request, answered with no-store (not cacheable by design, because it returns real price and stock).

Does it depend on other apps?

The block depends on vtex.product-context, vtex.order-items, vtex.order-manager, vtex.css-handles, vtex.render-runtime, vtex.format-currency, and vtex.pixel-manager, plus vtex.store@2.x as a peer dependency. The summary currency is resolved by vtex.format-currency using the store configuration.

Checklist before publishing

• App installed in the correct account and workspace.
• Dependency declared in the theme and vtex link restarted.
• Block declared inside the product page, with product context.
• Website ID entered and license confirmed on the product page.
• ValorRendimiento and UnidadMedida specifications created and assigned to the widget's categories.
• Yield greater than 0 on the product or the SKU.
• Unit of measurement loaded in a recognized short form.
• SKU-level yield where it varies per variation.
• Quantity, price, and stock validated against the catalog on a pilot product.
• Add-to-cart and minicart tested end to end.
• Checkout customData registration coordinated, if traceability is required.
• Override CSS reviewed on desktop and mobile.