Skip to main content

Add Bike Leasing Widget

IMPORTANT – Germany only

The Bike Leasing Widget is intended exclusively for use in the German market.
All leasing calculations are based on the German tax and social security system and are not valid for other countries or tax regimes.

This documentation describes the complete integration of the leasing widget into your shop. It is structurally based on the Smartfit docs for product sizing and extends them with all required variables/attributes for the leasing widget as well as platform-independent examples.

1) Requirements & Setup​

1.1 Include the Loader Script​

Include the loader script once (e.g., in the <head>):

<script type="module" src="https://widget3.smartfit.online/?apiKey={{ ADD YOUR API KEY }}"></script>

The loader is required because it initializes the Smartfit custom elements.

ℹ️ INFO
This is the same loader that is used for the Smartfit Sizing Widget – if it is already included, you don’t need to add an additional script. You will receive your API key from your Smartfit account.

1.2 Load Only on Relevant Pages​

Only load the widget on product detail pages where leasing is appropriate (e.g., bikes/e-bikes). Use simple route/template or category checks to ensure the script is not loaded on listing, cart, or checkout pages.

2) Custom Element & Attributes​

The leasing widget is embedded using the custom element <sf-product-leasing>. The following attributes are technically required:

  • name (String, required) – Product name as displayed on the PDP.
  • sale-price (Number, required) – Current sales price as a decimal number (e.g., 3499.00), without currency symbol.
  • retail-price (Number, required) – MSRP/Compare-at price as a decimal number.

Optional attributes:

  • dealer-leasing-price (Number, optional) – Dealer price for leasing calculation as a decimal.
  • style-name (String, optional): If a custom style was set up for you, reference it here via the style name.
  • workflow (String, optional) – Backend workflow/profile (e.g., leasing-rate).

Formatting Requirements:

  • Decimal point . as separator, no thousand separators/spaces, no currency symbols.
  • Values can be numbers or numeric strings (e.g., "3499.00").

Minimal Example:

<sf-product-leasing
  name="{{ Product name variable }}"
  sale-price="{{ Sale price variable }}"
  retail-price="{{ Retail price variable }}"
>
</sf-product-leasing>
Result
Default Product Leasing Button
info

The color will match the CTA color configured in Smartfit Analytics.

This will enable you to test the Smartfit Leasing Widget with a default version. Please continue for more customization.

3) Custom Button​

To design the button yourself, see Custom Button

4) Variant Changes (Short Version)​

For variant switching, update values directly on the widget:

<script>
  const widget = document.querySelector("#leasing-widget");
  widget?.setAttribute("sale-price", newSalePrice);
  widget?.setAttribute("retail-price", newRetailPrice);
  widget?.setAttribute("dealer-leasing-price", newDealerPrice);
  widget?.setAttribute("name", newTitle);
</script>
warning

Ensure the script runs after the browser has created the HTML element.

Option 1 - Place the script tag after the widget HTML element.

Option 2 - Attach the function to the window load event.

5) Go‑Live Checklist​

  • Loader script correctly included (with API key).
  • Widget only loaded on relevant PDPs (route/template/category checks).
  • Attribute values present and properly formatted (name, sale-price, retail-price; optional: dealer-leasing-price, workflow).
  • Exactly one CTA or data-sf-button set per template.
  • Variant switch reliably triggers updateLeasingWidget(...).

6) Differences from Product Sizing Integration (Short Overview)​

  • Element: Leasing uses <sf-product-leasing> with template slots; sizing uses <sf-product-sizing> (options incl. fallback).
  • Attributes: Sizing requires e.g., global-id, variant-id, image, price, product-type; leasing focuses on price/leasing attributes (sale-price, retail-price, dealer-leasing-price) plus name & optionally workflow.
  • Content: Leasing renders values via slots (rate, savings, etc.); sizing primarily configures the button/widget.
  • CTA: Leasing auto-detects CTA or uses data-sf-button; sizing defines button as a child element (with fallback option).