Using directives in Store Builder

Use directives to display live product and order data in your HTML without writing custom JavaScript or calling the FastSpring API. You can use directives to dynamically show values like product names, images, prices, discounts, and order totals.

Why use directives?

Display live product and order data in your HTML without writing JavaScript:

No custom JavaScript required

Populate dynamic values using HTML attributes only.

Real-time updates

Show live pricing, cart, and order data as the buyer interacts.

Minimal setup

Add FastSpring-powered content without managing API responses.

What this guide covers

This guide explains how to:

Use product-level directives like data-fsc-item-display and data-fsc-item-price
Use order-level directives like data-fsc-order-total and data-fsc-order-country

Quick start

Follow these steps to add directives to your Store Builder integration:

Add the Store Builder script

<!-- Load the FastSpring Store Builder script -->
<script
  id="fsc-api"
  src="https://sbl.onfastspring.com/sbl/1.0.3/fastspring-builder.min.js"
  type="text/javascript"
  data-storefront="your-storefront-URL">
</script>

📘
Replace your-storefront-URL with the full path to a checkout in your store.

Use a directive in your HTML

Here's how to display a product's name using data-fsc-item-display:
```

<span data-fsc-item-path="your-product-path" data-fsc-item-display></span>
```
💡
What it does: Renders the display name of the product in this span.
What to update: Replace your-product-path with the path of a product from your store.

Product-level directives

Product-level directives allow you to fetch and display dynamic information for a single product using HTML attributes. These directives can be used to show product names, images, prices, descriptions, and more without making API calls.

Requirements

Before using product-level directives, make sure you:

Include the FastSpring Store Builder script

<script
  id="fsc-api"
  src="https://sbl.onfastspring.com/sbl/1.0.3/fastspring-builder.min.js"
  type="text/javascript"
  data-storefront="your-storefront-URL">
</script>

📘
Replace your-storefront-URL with the full path to a checkout in your store.

Attribute	Description
`id`	Identifies the script block (must be set to `fsc-api`)
`src`	Specifies the version of the Store Builder
`type`	Declares the script as JavaScript
`data-storefront`	The storefront URL this script will connect to

Add the data-fsc-item-path attribute to each product element. This tells Store Builder which product to pull data from.
Use product paths that exist in your store checkout. Directives will only populate if the product was added to the homepage of your checkout.

Product-level directives summary

The table below provides an overview of available product-level directives, what they do, and examples of how they can be used to display real-time product information in your HTML.

Directive	Description	Example
`data-fsc-item-path`	Specifies the unique product path defined by the seller. This attribute is required on every product-level HTML tag and accepts a single parameter to ensure the correct product data is retrieved.	View Code
`data-fsc-item-display`	Renders the product name as set in your FastSpring store, ensuring the title is clearly visible on your website.	View Code
`data-fsc-item-image`	Retrieves the URL for the product image so it can be displayed on your website.	View Code
`data-fsc-item-description-summary`	Shows a brief description of the product, giving users a quick overview of its features.	View Code
`data-fsc-item-description-full`	Displays the complete product description with detailed specifications and information from your store.	View Code
`data-fsc-item-description-action`	Shows a call-to-action text that encourages users to view additional product details.	View Code
`data-fsc-item-selected`	A boolean flag that, when true, pre-selects the product in the order session to streamline checkout.	View Code
`data-fsc-item-path-element`	Retrieves the element containing the product path, helping to maintain consistent product identification.	View Code
`data-fsc-item-pid`	Fetches the unique product ID used for inventory tracking and order processing.	View Code
`data-fsc-item-quantity`	Displays the quantity of the product selected by the user.	View Code
`data-fsc-item-quantity-value`	Acts as a value setter to update the product quantity when changes are made.	View Code
`data-fsc-item-quantityEditable`	A boolean flag that allows users to edit the product quantity directly on your website.	View Code
`data-fsc-item-removable`	A boolean flag that lets users remove the product from their order if needed.	View Code
`data-fsc-item-unitDiscountValue`	Specifies the discount amount for each unit, reducing the price on a per-item basis.	View Code
`data-fsc-item-discountPercentValue`	Displays the discount as a percentage per unit, useful for percentage-based pricing adjustments.	View Code
`data-fsc-item-discountTotal`	Calculates the total discount for the product line by summing the discounts on each unit.	View Code
`data-fsc-item-discountTotalValue`	Provides the overall discount amount as a number for final pricing calculations.	View Code
`data-fsc-item-price`	Displays the product's price with a currency symbol as set in your FastSpring store, formatted for clear display.	View Code
`data-fsc-item-priceValue`	Shows the raw numeric price (e.g. 19.99). You can retrieve this value using JavaScript for custom formatting or calculations.	View Code
`data-fsc-item-priceTotal`	Calculates the total price when multiple units are selected based on the individual price.	View Code
`data-fsc-item-priceTotalValue`	Provides the overall price as a numeric value for precise order calculations.	View Code
`data-fsc-item-unitPrice`	Displays the unit price after any discounts have been applied, clarifying the cost per item.	View Code
`data-fsc-item-unitPriceValue`	Shows the discounted unit price as a plain number for internal processing.	View Code
`data-fsc-item-total`	Displays the overall cost for the product line, taking quantity and discounts into account.	View Code
`data-fsc-item-totalValue`	Provides the total cost as a numeric value for final order processing.	View Code
`data-fsc-item-priceWithoutTax`	Shows the base price before tax is added, allowing you to separate product cost from tax.	View Code
`data-fsc-item-priceValueWithoutTax`	Displays the tax-free price as a numeric value for detailed cost breakdowns.	View Code
`data-fsc-driver-item-path-value`	Replaces the current product path with a new identifier to enable an upsell option. The new value should be an existing product identifier and must be applied to the correct element so the intended product is referenced.	View Code
`data-fsc-autoapply`	Automatically applies changes without a manual click, simplifying the checkout process.	View Code
`data-fsc-item-selection-smartdisplay`	Controls element visibility based on whether the product is selected, allowing related information to be shown or hidden dynamically.	View Code
`data-fsc-item-selection-smartdisplay-inverse`	Displays elements only when the product is not selected, useful for showing alternative options or messages.	View Code

Detailed product-level directive examples

Below are detailed examples for each product-level directive. Expand each section to see the code snippet, what it does, and how to use it.

data-fsc-item-display

HTML markup + FastSpring script setup:

<!-- Label and span to display the product's name -->
Product Display Name:
<span data-fsc-item-path="your-product-path" data-fsc-item-display>
  <!-- This value will be dynamically replaced -->
</span>

<!-- Load the FastSpring Store Builder script -->
<script
  id="fsc-api"
  src="https://sbl.onfastspring.com/sbl/1.0.3/fastspring-builder.min.js"
  type="text/javascript"
  data-storefront="your-storefront-URL">
</script>

What it does: Dynamically retrieves and displays the product's display name from your FastSpring store, directly in your HTML.

What to update:

Replace your-product-path with the path of a product from your store.
Replace your-storefront-URL with the full path to a checkout in your store.

data-fsc-item-image

HTML markup + FastSpring script setup:

<!-- Display the product image URL -->
Image URL:
<span data-fsc-item-path="your-product-path" data-fsc-item-image>
  <!-- This value will be dynamically replaced -->
</span>

<!-- Display the actual product image -->
Product Image:
<img data-fsc-item-path="your-product-path" data-fsc-item-image />

<!-- Load the FastSpring Store Builder script -->
<script
  id="fsc-api"
  src="https://sbl.onfastspring.com/sbl/1.0.3/fastspring-builder.min.js"
  type="text/javascript"
  data-storefront="your-storefront-URL">
</script>

What it does: Dynamically displays the product's image URL as text or directly renders the product image on your page.

What to update:

Replace your-product-path with the path of a product from your store.
Replace your-storefront-URL with the full path to a checkout in your store.

data-fsc-item-description-summary

HTML markup + FastSpring script setup:

<!-- Display the product's short description -->
Summary Description:<br />
<span data-fsc-item-path="your-product-path" data-fsc-item-description-summary>
  <!-- This value will be dynamically replaced -->
</span>

<!-- Load the FastSpring Store Builder script -->
<script
  id="fsc-api"
  src="https://sbl.onfastspring.com/sbl/1.0.3/fastspring-builder.min.js"
  type="text/javascript"
  data-storefront="your-storefront-URL">
</script>

What it does: Dynamically displays the short description (summary) for the specified product.

What to update:

Replace your-product-path with the path of a product from your store.
Replace your-storefront-URL with the full path to a checkout in your store.

data-fsc-item-description-full

HTML markup + FastSpring script setup:

<!-- Display the product's full description -->
Full Description:<br />
<span data-fsc-item-path="your-product-path" data-fsc-item-description-full>
  <!-- This value will be dynamically replaced -->
</span>

<!-- Load the FastSpring Store Builder script -->
<script
  id="fsc-api"
  src="https://sbl.onfastspring.com/sbl/1.0.3/fastspring-builder.min.js"
  type="text/javascript"
  data-storefront="your-storefront-URL">
</script>

What it does: Dynamically displays the full description for the specified product.

What to update:

Replace your-product-path with the path of a product from your store.
Replace your-storefront-URL with the full path to a checkout in your store.

data-fsc-item-description-action

HTML markup + FastSpring script setup:

<!-- Display the product's call-to-action text -->
Product Call to Action:<br />
<span data-fsc-item-path="your-product-path" data-fsc-item-description-action>
  <!-- This value will be dynamically replaced -->
</span>

<!-- Load the FastSpring Store Builder script -->
<script
  id="fsc-api"
  src="https://sbl.onfastspring.com/sbl/1.0.3/fastspring-builder.min.js"
  type="text/javascript"
  data-storefront="your-storefront-URL">
</script>

What it does: Dynamically displays the call-to-action text defined for the specified product.

What to update:

Replace your-product-path with the path of a product from your store.
Replace your-storefront-URL with the full path to a checkout in your store.

data-fsc-item-selected

HTML markup + FastSpring script setup:

<!-- Check if the product is currently added to the order -->
Is this item currently added to the order:<br />
<span data-fsc-item-path="your-product-path" data-fsc-item-selected>
  <!-- This value will be dynamically replaced -->
</span>
<br /><br />

<!-- Button: Add to Cart (shown only if product is NOT selected) -->
<button
  data-fsc-item-path-value="your-product-path"
  data-fsc-action="Add"
  data-fsc-item-path="your-product-path"
  data-fsc-item-selection-smartdisplay-inverse>
  Add to Cart
</button>

<!-- Button: Remove from Cart (shown only if product IS selected) -->
<button
  data-fsc-item-path-value="your-product-path"
  data-fsc-action="Remove"
  data-fsc-item-path="your-product-path"
  data-fsc-item-selection-smartdisplay>
  Remove from Cart
</button>

<!-- Load the FastSpring Store Builder script -->
<script
  id="fsc-api"
  src="https://sbl.onfastspring.com/sbl/1.0.3/fastspring-builder.min.js"
  type="text/javascript"
  data-storefront="your-storefront-URL">
</script>

What it does: Dynamically indicates whether a product is currently in the cart, displaying either "true" (selected) or "false" (not selected). The buttons automatically toggle visibility based on the selection state of the product.

What to update:

Replace your-product-path with the path of a product from your store.
Replace your-storefront-URL with the full path to a checkout in your store.

data-fsc-item-path-element

HTML markup + FastSpring script setup:

<!-- Displays the product's path -->
Element:<br />
<span data-fsc-item-path="your-product-path" data-fsc-item-path-element>
  <!-- This value will be dynamically replaced -->
</span>

<!-- Load the FastSpring Store Builder script -->
<script
  id="fsc-api"
  src="https://sbl.onfastspring.com/sbl/1.0.3/fastspring-builder.min.js"
  type="text/javascript"
  data-storefront="your-storefront-URL">
</script>

What it does: Dynamically displays the product's path (identifier) as defined in your FastSpring dashboard.

What to update:

Replace your-product-path with the path of a product from your store.
Replace your-storefront-URL with the full path to a checkout in your store.

data-fsc-item-quantity

HTML markup + FastSpring script setup:

Quantity:
<span data-fsc-item-path="your-product-path" data-fsc-item-quantity>
  <!-- The current quantity in the cart will be populated here -->
</span>
<br /><br />

<!-- Select to allow users to choose quantity -->
<select id="qty">
  <option value="1">1</option>
  <option value="2">2</option>
  <option value="3">3</option>
  <option value="4">4</option>
  <option value="5">5</option>
</select>

<!-- Button to trigger quantity update -->
<button onclick="updateQuantity();">
  Update Quantity
</button>

<!-- Load the FastSpring Store Builder script -->
<script
  id="fsc-api"
  src="https://sbl.onfastspring.com/sbl/1.0.3/fastspring-builder.min.js"
  type="text/javascript"
  data-storefront="your-storefront-URL">
</script>

JavaScript method function:

function updateQuantity() {
  const qty = document.getElementById("qty").value;
  fastspring.builder.update("your-product-path", qty);
}

What it does: Shows the current quantity of a specific item in the cart and provides an interface to let the user update that quantity dynamically.

What to update:

Replace your-product-path with the path of a product from your store.
Replace your-storefront-URL with the full path to a checkout in your store.
Rename updateQuantity if you're using a different function name.
Adjust quantity options in the <select> element as needed.

data-fsc-item-quantityEditable

HTML markup + FastSpring script setup:

Quantity Editable:
<span data-fsc-item-path="your-product-path" data-fsc-item-quantityEditable>
  <!-- Whether the item's quantity is editable (true/false) will be populated here -->
</span>

<!-- Load the FastSpring Store Builder script -->
<script
  id="fsc-api"
  src="https://sbl.onfastspring.com/sbl/1.0.3/fastspring-builder.min.js"
  type="text/javascript"
  data-storefront="your-storefront-URL">
</script>

What it does: Displays whether the quantity of a specific item can be edited by the buyer (true or false). This setting is configured in the FastSpring dashboard.

What to update:

Replace your-product-path with the path of a product from your store.
Replace your-storefront-URL with the full path to a checkout in your store.

data-fsc-item-removable

HTML markup + FastSpring script setup:

Removable:
<span data-fsc-item-path="your-product-path" data-fsc-item-removable>
  <!-- Whether the item can be removed from the cart (true/false) will be populated here -->
</span>

<!-- Load the FastSpring Store Builder script -->
<script
  id="fsc-api"
  src="https://sbl.onfastspring.com/sbl/1.0.3/fastspring-builder.min.js"
  type="text/javascript"
  data-storefront="your-storefront-URL">
</script>

What it does: Indicates whether an item can be removed from the cart (true or false). This setting is configured within your FastSpring dashboard.

What to update:

Replace your-product-path with the path of a product from your store.
Replace your-storefront-URL with the full path to a checkout in your store.

data-fsc-item-unitDiscountValue

HTML markup + FastSpring script setup:

Unit Discount Value:
<span data-fsc-item-path="your-product-path" data-fsc-item-unitDiscountValue>
  <!-- The per-unit discount amount for this item will be populated here -->
</span>

<!-- Load the FastSpring Store Builder script -->
<script
  id="fsc-api"
  src="https://sbl.onfastspring.com/sbl/1.0.3/fastspring-builder.min.js"
  type="text/javascript"
  data-storefront="your-storefront-URL">
</script>

What it does: Displays the per-unit discount amount currently applied to the item.

What to update:

Replace your-product-path with the path of a product configured with a discount in your store.
Replace your-storefront-URL with the full path to a checkout in your store.

data-fsc-item-discountPercentValue

HTML markup + FastSpring script setup:

Discount Percent Value:
<span data-fsc-item-path="your-product-path" data-fsc-item-discountPercentValue>
  <!-- The discount percentage applied to this item will be populated here -->
</span>

<!-- Load the FastSpring Store Builder script -->
<script
  id="fsc-api"
  src="https://sbl.onfastspring.com/sbl/1.0.3/fastspring-builder.min.js"
  type="text/javascript"
  data-storefront="your-storefront-URL">
</script>

What it does: Shows the percentage discount currently applied to the item.

What to update:

Replace your-product-path with the path of a discounted product from your store.
Replace your-storefront-URL with the full path to a checkout in your store.

data-fsc-item-discountTotal

HTML markup + FastSpring script setup:

<!-- Display the total discount applied to the item -->
Discount Total:
<span data-fsc-item-path="your-product-path" data-fsc-item-discountTotal>
  <!-- The item's total discount amount will populate here -->
</span>

<!-- Optional: Display current order total -->
Order Total:
<span data-fsc-order-total>
  <!-- The order's current total will populate here -->
</span>

<!-- Load the FastSpring Store Builder script -->
<script
  id="fsc-api"
  src="https://sbl.onfastspring.com/sbl/1.0.3/fastspring-builder.min.js"
  type="text/javascript"
  data-storefront="your-storefront-URL">
</script>

What it does: Displays the total discount amount applied to an item across all units in the cart.

What to update:

Replace your-product-path with the path of a discounted product from your store.
Replace your-storefront-URL with the full path to a checkout in your store.

data-fsc-item-discountTotalValue

HTML markup + FastSpring script setup:

<!-- Display the numeric total discount value for the item -->
Discount Total Value:
<span data-fsc-item-path="your-product-path" data-fsc-item-discountTotalValue>
  <!-- The numeric total discount value will populate here -->
</span>

<!-- Optional: Display current order total -->
Order Total:
<span data-fsc-order-total>
  <!-- The order's current total will populate here -->
</span>

<!-- Load the FastSpring Store Builder script -->
<script
  id="fsc-api"
  src="https://sbl.onfastspring.com/sbl/1.0.3/fastspring-builder.min.js"
  type="text/javascript"
  data-storefront="your-storefront-URL">
</script>

What it does: Displays the numeric value of the total discount applied to an item across all units in the cart.

What to update:

Replace your-product-path with the path of a discounted product from your store.
Replace your-storefront-URL with the full path to a checkout in your store.

data-fsc-item-priceValue

HTML markup + FastSpring script setup:

<!-- Display the item's numeric price value -->
Price Value:
<span data-fsc-item-path="your-product-path" data-fsc-item-priceValue>
  <!-- The numeric item price without currency formatting will populate here -->
</span>

<!-- Load the FastSpring Store Builder script -->
<script
  id="fsc-api"
  src="https://sbl.onfastspring.com/sbl/1.0.3/fastspring-builder.min.js"
  type="text/javascript"
  data-storefront="your-storefront-URL">
</script>

What it does: Shows the numeric price of the specified product without currency symbols or formatting (useful for calculations or custom formatting).

What to update:

Replace your-product-path with the path of a product from your store.
Replace your-storefront-URL with the full path to a checkout in your store.

data-fsc-item-priceTotal

HTML markup + FastSpring script setup:

<!-- Display the total base price (before discounts) multiplied by quantity -->
Price Total:
<span data-fsc-item-path="your-product-path" data-fsc-item-priceTotal>
  <!-- The item's total base price (price × quantity, excluding discounts) will populate here -->
</span>

<!-- Load the FastSpring Store Builder script -->
<script
  id="fsc-api"
  src="https://sbl.onfastspring.com/sbl/1.0.3/fastspring-builder.min.js"
  type="text/javascript"
  data-storefront="your-storefront-URL">
</script>

What it does: Displays the item's total base price (unit price multiplied by quantity), without considering discounts.

📘

Includes tax for non-US transactions.

Excludes tax for US transactions.

What to update:

Replace your-product-path with the path of a product from your store.
Replace your-storefront-URL with the full path to a checkout in your store.

data-fsc-item-priceTotalValue

HTML markup + FastSpring script setup:

<!-- Display the numeric total price of the item (unit price × quantity, excluding discounts) -->
Price Total Value:
<span data-fsc-item-path="your-product-path" data-fsc-item-priceTotalValue>
  <!-- The numeric total price of the item will populate here -->
</span>

<!-- Load the FastSpring Store Builder script -->
<script
  id="fsc-api"
  src="https://sbl.onfastspring.com/sbl/1.0.3/fastspring-builder.min.js"
  type="text/javascript"
  data-storefront="your-storefront-URL">
</script>

What it does: Displays the numeric total price of an item (unit price × quantity). It does not reflect discounts or tax adjustments from promo codes.

What to update:

Replace your-product-path with the path of a product from your store.
Replace your-storefront-URL with the full path to a checkout in your store.

data-fsc-item-unitPrice

HTML markup + FastSpring script setup:

<!-- Display the unit price of the item, reflecting any discounts -->
Unit Price:
<span data-fsc-item-path="your-product-path" data-fsc-item-unitPrice>
  <!-- The unit price of the item (after discount) will populate here -->
</span>

<!-- Load the FastSpring Store Builder script -->
<script
  id="fsc-api"
  src="https://sbl.onfastspring.com/sbl/1.0.3/fastspring-builder.min.js"
  type="text/javascript"
  data-storefront="your-storefront-URL">
</script>

What it does: Displays the unit price for a single item, taking into account any applied discounts (e.g., promo codes or quantity-based discounts).

What to update:

Replace your-product-path with the path of a product from your store.
Replace your-storefront-URL with the full path to a checkout in your store.

data-fsc-item-unitPriceValue

HTML markup + FastSpring script setup:

<!-- Display numeric unit price of the item, reflecting any discounts -->
Unit Price Value:
<span data-fsc-item-path="your-product-path" data-fsc-item-unitPriceValue>
  <!-- The numeric unit price of the item (after discount) will populate here -->
</span>

<!-- Load the FastSpring Store Builder script -->
<script
  id="fsc-api"
  src="https://sbl.onfastspring.com/sbl/1.0.3/fastspring-builder.min.js"
  type="text/javascript"
  data-storefront="your-storefront-URL">
</script>

What it does: Displays the numeric unit price value (without currency symbols or formatting) of a single item, reflecting any discounts or promotions applied.

What to update:

Replace your-product-path with the path of a product from your store.
Replace your-storefront-URL with the full path to a checkout in your store.

data-fsc-item-total

HTML markup + FastSpring script setup:

<!-- Display total price for the item(s) in the cart, including discounts -->
Total:
<span data-fsc-item-path="your-product-path" data-fsc-item-total>
  <!-- The item's total price (quantity × unit price minus discounts) will populate here -->
</span>

<!-- Load the FastSpring Store Builder script -->
<script
  id="fsc-api"
  src="https://sbl.onfastspring.com/sbl/1.0.3/fastspring-builder.min.js"
  type="text/javascript"
  data-storefront="your-storefront-URL">
</script>

What it does: Displays the total price for the selected item, including quantity, unit price, and discounts. In most cases, these values exclude order-level taxes. For non-US transactions, tax may be included.

What to update:

Replace your-product-path with the path of a product from your store.
Replace your-storefront-URL with the full path to a checkout in your store.

data-fsc-item-totalValue

HTML markup + FastSpring script setup:

<!-- Display numeric total price for the item(s) in the cart, including discounts -->
Total Value:
<span data-fsc-item-path="your-product-path" data-fsc-item-totalValue>
  <!-- The numeric total price (quantity × unit price minus discounts) will populate here -->
</span>

<!-- Load the FastSpring Store Builder script -->
<script
  id="fsc-api"
  src="https://sbl.onfastspring.com/sbl/1.0.3/fastspring-builder.min.js"
  type="text/javascript"
  data-storefront="your-storefront-URL">
</script>

What it does: Shows the numeric total price for the item, accounting for quantity, unit price, and any discounts. Taxes and fees are not included.

What to update:

Replace your-product-path with the path of a product from your store.
Replace your-storefront-URL with the full path to a checkout in your store.

data-fsc-item-priceWithoutTax

HTML markup + FastSpring script setup:

<!-- Display price including tax -->
Price:
<span data-fsc-item-path="your-product-path" data-fsc-item-price>
  <!-- The item's price including applicable tax will populate here -->
</span>

<!-- Display price excluding tax -->
Price without tax:
<span data-fsc-item-path="your-product-path" data-fsc-item-priceWithoutTax>
  <!-- The item's price excluding tax will populate here -->
</span>

<!-- Display the order's total tax -->
Tax:
<span data-fsc-order-tax>
  <!-- The total order tax will populate here -->
</span>

<!-- Load the FastSpring Store Builder script -->
<script
  id="fsc-api"
  src="https://sbl.onfastspring.com/sbl/1.0.3/fastspring-builder.min.js"
  type="text/javascript"
  data-storefront="your-storefront-URL">
</script>

What it does: Displays the item's price without tax separately from its price including tax. Useful for regions where prices typically include VAT.

What to update:

Replace your-product-path with the path of a product from your store.
Replace your-storefront-URL with the full path to a checkout in your store.

data-fsc-item-priceValueWithoutTax

HTML markup + FastSpring script setup:

<!-- Display numeric price including tax -->
Price:
<span data-fsc-item-path="your-product-path" data-fsc-item-priceValue>
  <!-- The numeric price including applicable tax will populate here -->
</span>

<!-- Display numeric price excluding tax -->
Price value without tax:
<span data-fsc-item-path="your-product-path" data-fsc-item-priceValueWithoutTax>
  <!-- The numeric price excluding tax will populate here -->
</span>

<!-- Display the order's total tax -->
Tax:
<span data-fsc-order-tax>
  <!-- The total order tax will populate here -->
</span>

<!-- Load the FastSpring Store Builder script -->
<script
  id="fsc-api"
  src="https://sbl.onfastspring.com/sbl/1.0.3/fastspring-builder.min.js"
  type="text/javascript"
  data-storefront="your-storefront-URL">
</script>

What it does: Displays the numeric price of an item excluding tax, alongside the numeric price including tax. Useful for calculations or presenting detailed pricing breakdowns.

What to update:

Replace your-product-path with the path of a product from your store.
Replace your-storefront-URL with the full path to a checkout in your store.

data-fsc-driver-item-path-value

HTML markup + FastSpring script setup:

<!-- Display products currently in the cart -->
<div
  data-fsc-selections-smartdisplay
  data-fsc-items-container="shopping-cart"
  data-fsc-filter="selected=true">
  <!-- Cart items will populate here -->
</div>

<!-- Button to add an upsell item -->
<button
  data-fsc-item-path-value="upsell"
  data-fsc-action="Add">
  Add to Cart
</button>

<!-- Button to replace an existing item with an upsell -->
<button
  data-fsc-item-path-value="upsell"
  data-fsc-driver-item-path-value="your-primary-product-path"
  data-fsc-action="Replace">
  Replace
</button>

<!-- Load the FastSpring Store Builder script -->
<script
  id="fsc-api"
  src="https://sbl.onfastspring.com/sbl/1.0.3/fastspring-builder.min.js"
  type="text/javascript"
  data-storefront="your-storefront-URL">
</script>

<!-- Handlebars template to render cart items -->
<script
  data-fsc-template-for="shopping-cart"
  type="text/x-handlebars-template">
  <ul>
    {{#each items}}
      {{#each items}}
        <li>{{this.display}}</li>
      {{/each}}
    {{/each}}
  </ul>
</script>

What it does: When used with actions like Replace, this directive specifies the existing item (data-fsc-driver-item-path-value) in the cart that will be replaced by another product (often an upsell). Useful for upgrading or swapping items.

What to update:

Replace your-primary-product-path with the path of the main product currently in the cart.
Replace upsell with the product path of the upsell item you want to add or replace.
Replace your-storefront-URL with the full path to a checkout in your store.
Adjust or remove the optional JavaScript snippet based on your specific use case.

data-fsc-autoapply

HTML markup + FastSpring script setup:

<!-- Display the current quantity of the item in the cart -->
Quantity Currently in Cart:
<span data-fsc-item-path="your-product-path" data-fsc-item-quantity>
  <!-- The current quantity will populate here -->
</span>

<!-- Dropdown to automatically update product quantity -->
<select
  data-fsc-autoapply
  data-fsc-item-quantity-value
  data-fsc-item-quantity
  data-fsc-item-path-value="your-product-path"
  data-fsc-item-path="your-product-path"
  data-fsc-action="Update">
  <option value="1">1</option>
  <option value="2">2</option>
  <option value="3">3</option>
  <option value="4">4</option>
  <option value="5">5</option>
</select>

<!-- Load the FastSpring Store Builder script -->
<script
  id="fsc-api"
  src="https://sbl.onfastspring.com/sbl/1.0.3/fastspring-builder.min.js"
  type="text/javascript"
  data-storefront="your-storefront-URL">
</script>

What it does: Automatically applies the selected quantity to the cart without requiring additional user action (such as clicking a button). The data-fsc-autoapply directive triggers the update as soon as the user selects a new quantity.

What to update:

Replace your-product-path with the product path from your FastSpring store.
Replace your-storefront-URL with the full path to a checkout in your store.
Adjust the quantity options (<option> values) to match your product availability.
Remove the optional JavaScript snippet if your product is already added to the cart elsewhere.

data-fsc-item-selection-smartdisplay

HTML markup + FastSpring script setup:

<!-- Displayed when the item is in the cart -->
<span data-fsc-item-path="your-product-path" data-fsc-item-selection-smartdisplay>
  The product is in the cart.
</span>

<!-- Displayed when the item is not in the cart -->
<span data-fsc-item-path="your-product-path" data-fsc-item-selection-smartdisplay-inverse>
  The product is not in the cart.
</span>

<!-- Button to add the product to the cart -->
<button
  data-fsc-item-path-value="your-product-path"
  data-fsc-action="Add"
  data-fsc-item-path="your-product-path"
  data-fsc-item-selection-smartdisplay-inverse>
  Add to Cart
</button>

<!-- Button to remove the product from the cart -->
<button
  data-fsc-item-path-value="your-product-path"
  data-fsc-action="Remove"
  data-fsc-item-path="your-product-path"
  data-fsc-item-selection-smartdisplay>
  Remove from Cart
</button>

<!-- Load the FastSpring Store Builder script -->
<script
  id="fsc-api"
  src="https://sbl.onfastspring.com/sbl/1.0.3/fastspring-builder.min.js"
  type="text/javascript"
  data-storefront="your-storefront-URL">
</script>

What it does: Conditionally displays elements based on whether the product is currently in the cart or not.

What to update:

Replace your-product-path with your product's path.
Replace your-storefront-URL with your checkout URL.
Customize the display messages as desired.

data-fsc-item-selection-smartdisplay-inverse

HTML markup + FastSpring script setup:

<!-- Displayed when the product is in the cart -->
<span data-fsc-item-path="your-product-path" data-fsc-item-selection-smartdisplay>
  The product is in the cart.
</span>

<!-- Displayed when the product is not in the cart -->
<span data-fsc-item-path="your-product-path" data-fsc-item-selection-smartdisplay-inverse>
  The product is not in the cart.
</span>

<!-- Button to add product to cart (displayed only when product is not in cart) -->
<button
  data-fsc-item-path-value="your-product-path"
  data-fsc-action="Add"
  data-fsc-item-path="your-product-path"
  data-fsc-item-selection-smartdisplay-inverse>
  Add to Cart
</button>

<!-- Button to remove product from cart (displayed only when product is in cart) -->
<button
  data-fsc-item-path-value="your-product-path"
  data-fsc-action="Remove"
  data-fsc-item-path="your-product-path"
  data-fsc-item-selection-smartdisplay>
  Remove from Cart
</button>

<!-- Load the FastSpring Store Builder script -->
<script
  id="fsc-api"
  src="https://sbl.onfastspring.com/sbl/1.0.3/fastspring-builder.min.js"
  type="text/javascript"
  data-storefront="your-storefront-URL">
</script>

What it does: Conditionally displays elements when the product is not currently in the cart.

What to update:

Replace your-product-path with your product's path.
Replace your-storefront-URL with your checkout URL.
Customize the display messages as desired.

Order-level directives

Order-level directives retrieve and display details about the current order, including pricing, discounts, taxes, and localization information. These directives help you build a real-time order summary without custom JavaScript.

Requirements

Before using order-level directives, make sure you:

Include the FastSpring Store Builder script

<script
  id="fsc-api"
  src="https://sbl.onfastspring.com/sbl/1.0.3/fastspring-builder.min.js"
  type="text/javascript"
  data-storefront="your-storefront-URL">
</script>

📘
Replace your-storefront-URL with the full path to a checkout in your store.

Attribute	Description
`id`	Identifies the script block (must be set to `fsc-api`)
`src`	Specifies the version of the Store Builder
`type`	Declares the script as JavaScript
`data-storefront`	The storefront URL this script will connect to

Include order directive attributes on your HTML elements. Use attributes like data-fsc-order-total, data-fsc-order-tax, and others to display order details dynamically.

Order-level directives summary

The table below provides an overview of available order-level directives, their functions, and examples of how they can be used to display real-time order details in your HTML.

Directive	Description	Example
`data-fsc-order-discountTotal`	Shows the overall discount applied to the order by combining the discounts from individual items.	View Code
`data-fsc-order-discountTotalValue`	Retrieves the total discount amount as a numeric value for accurate order calculations.	View Code
`data-fsc-order-total`	Displays the order subtotal (total amount before taxes are applied).	View Code
`data-fsc-order-totalValue`	Provides the numeric value of the order subtotal for internal processing.	View Code
`data-fsc-order-promocode`	Displays any promo code that has been applied to the order.	View Code
`data-fsc-promocode-value`	Provides an input field that lets users enter a promo code for the order.	View Code
`data-fsc-order-taxType`	Indicates the type of tax (such as VAT or GST) applied to the order.	View Code
`data-fsc-taxid-value`	Enables an input for users to enter a Tax ID, which may be used to exempt VAT from the order.	View Code
`data-fsc-order-tax`	Displays the tax amount as shown to the customer on the order summary.	View Code
`data-fsc-order-taxRate`	Retrieves the tax rate as a percentage that is applied to the order.	View Code
`data-fsc-order-taxValue`	Provides the tax amount as a numeric value for backend processing.	View Code
`data-fsc-order-totalWithTax`	Shows the final order total after adding the calculated tax.	View Code
`data-fsc-order-currency`	Displays the three-letter currency code (e.g. USD, EUR) used for the transaction.	View Code
`data-fsc-order-country`	Shows the country associated with the order, typically determined by the customer's IP address.	View Code
`data-fsc-order-language`	Retrieves the language setting for the order based on the user's browser or store configuration.	View Code
`data-fsc-order-totalWithTaxValue`	Provides the final order total (including tax) as a numeric value for accurate processing.	View Code

Detailed order-level directive examples

Below are detailed examples for each order-level directive. Expand each section to see the code snippet, what it does, and how to use it.

data-fsc-order-discountTotal

HTML markup + FastSpring script setup:

<!-- Display the total discount applied to the entire order -->
Discount Total:
<span data-fsc-order-discountTotal>
  <!-- The order discount (e.g. $1.90) will be dynamically rendered here -->
</span>

<!-- Load the FastSpring Store Builder script -->
<script
  id="fsc-api"
  src="https://sbl.onfastspring.com/sbl/1.0.3/fastspring-builder.min.js"
  type="text/javascript"
  data-storefront="your-storefront-URL">
</script>

What it does: Displays the total discount amount applied to the order. This value appears when at least one product is in the cart, and a valid promo code is applied.

What to update:

Replace your-storefront-URL with the full path to a checkout in your store.

data-fsc-order-discountTotalValue

HTML markup + FastSpring script setup:

<!-- Display the numeric discount value applied to the entire order -->
Discount Total Value:
<span data-fsc-order-discountTotalValue>
  <!-- The numeric order discount (e.g. 1.9) will be dynamically rendered here -->
</span>

<!-- Load the FastSpring Store Builder script -->
<script
  id="fsc-api"
  src="https://sbl.onfastspring.com/sbl/1.0.3/fastspring-builder.min.js"
  type="text/javascript"
  data-storefront="your-storefront-URL">
</script>

What it does: Displays the raw discount amount (without currency formatting) applied to the entire order. This value only appears after a product is added and a valid promo code is applied.

What to update:

Replace your-storefront-URL with the full path to a checkout in your store.

data-fsc-order-total

HTML markup + FastSpring script setup:

<!-- Display the formatted order subtotal (before tax) -->
Order Total:
<span data-fsc-order-total>
  <!-- The order subtotal with currency (e.g. $19.00) will be dynamically rendered here -->
</span>

<!-- Load the FastSpring Store Builder script -->
<script
  id="fsc-api"
  src="https://sbl.onfastspring.com/sbl/1.0.3/fastspring-builder.min.js"
  type="text/javascript"
  data-storefront="your-storefront-URL">
</script>

What it does: Displays the formatted subtotal for the order, before tax. This value updates automatically when a product is added or removed or when a promo code is applied.

What to update:

Replace your-storefront-URL with the full path to a checkout in your store.

data-fsc-order-totalValue

HTML markup + FastSpring script setup:

<!-- Display the unformatted order subtotal as a raw number -->
Order Total Value:
<span data-fsc-order-totalValue>
  <!-- The numeric subtotal (e.g. 19.00) will be dynamically rendered here -->
</span>

<!-- Load the FastSpring Store Builder script -->
<script
  id="fsc-api"
  src="https://sbl.onfastspring.com/sbl/1.0.3/fastspring-builder.min.js"
  type="text/javascript"
  data-storefront="your-storefront-URL">
</script>

What it does: Displays the numeric subtotal for the order before tax, without currency formatting. This is useful for custom logic, calculations, or analytics.

What to update:

Replace your-storefront-URL with the full path to a checkout in your store.

data-fsc-order-totalWithTax

HTML markup + FastSpring script setup:

<!-- Display the full order total, including any applied tax -->
Order Total with Tax:
<span data-fsc-order-totalWithTax>
  <!-- The formatted total with tax (e.g. $20.23) will be dynamically rendered here -->
</span>

<!-- Load the FastSpring Store Builder script -->
<script
  id="fsc-api"
  src="https://sbl.onfastspring.com/sbl/1.0.3/fastspring-builder.min.js"
  type="text/javascript"
  data-storefront="your-storefront-URL">
</script>

What it does: Displays the complete order total, including calculated tax, based on the buyer's country or postal code. It helps show what the shopper will pay at checkout.

What to update:

Replace your-storefront-URL with the full path to a checkout in your store.

data-fsc-order-totalWithTaxValue

HTML markup + FastSpring script setup:

<!-- Display the numeric total with tax, useful for calculations or custom formatting -->
Order Total with Tax (Raw Value):
<span data-fsc-order-totalWithTaxValue>
  <!-- The unformatted numeric total with tax (e.g. 20.23) will be dynamically rendered here -->
</span>

<!-- Load the FastSpring Store Builder script -->
<script
  id="fsc-api"
  src="https://sbl.onfastspring.com/sbl/1.0.3/fastspring-builder.min.js"
  type="text/javascript"
  data-storefront="your-storefront-URL">
</script>

What it does: Renders the numeric total for the entire order, including tax. This is useful when running additional calculations, displaying a custom currency format, or passing the value to your scripts.

What to update:

Replace your-storefront-URL with the full path to a checkout in your store.

data-fsc-order-currency

HTML markup + FastSpring script setup:

<!-- Display the 3-letter currency code used for the current order -->
Order Currency:
<span data-fsc-order-currency>
  <!-- The currency code (e.g. USD, EUR, GBP) will be dynamically rendered here -->
</span>

<!-- Load the FastSpring Store Builder script -->
<script
  id="fsc-api"
  src="https://sbl.onfastspring.com/sbl/1.0.3/fastspring-builder.min.js"
  type="text/javascript"
  data-storefront="your-storefront-URL">
</script>

What it does: Displays the three-letter ISO currency code used for the current order (e.g. USD, EUR, GBP). This reflects the buyer's localization and is helpful for analytics or when building a custom price display.

What to update:

Replace your-storefront-URL with the full path to a checkout in your store.

data-fsc-order-country

HTML markup + FastSpring script setup:

<!-- Display the buyer's detected country -->
Order Country:
<span data-fsc-order-country>
  <!-- The country code (e.g. US, DE, CA) will be dynamically rendered here -->
</span>

<!-- Load the FastSpring Store Builder script -->
<script
  id="fsc-api"
  src="https://sbl.onfastspring.com/sbl/1.0.3/fastspring-builder.min.js"
  type="text/javascript"
  data-storefront="your-storefront-URL">
</script>

What it does: Displays the buyer's current country using a two-letter ISO code (e.g., US, DE, CA). This is typically based on the buyer's IP address and is used to localize pricing, taxes, and legal settings.

What to update:

Replace your-storefront-URL with the full path to a checkout in your store.

data-fsc-order-language

HTML markup + FastSpring script setup:

<!-- Display the detected checkout language -->
Order Language:
<span data-fsc-order-language>
  <!-- The language code (e.g. en, de, fr) will be dynamically rendered here -->
</span>

<!-- Load the FastSpring Store Builder script -->
<script
  id="fsc-api"
  src="https://sbl.onfastspring.com/sbl/1.0.3/fastspring-builder.min.js"
  type="text/javascript"
  data-storefront="your-storefront-URL">
</script>

What it does: Displays the buyer's checkout language as a two-letter ISO 639-1 code, such as en for English or fr for French. Browser settings, localization rules, or your configured session determine this.

What to update:

Replace your-storefront-URL with the full path to a checkout in your store.

data-fsc-order-promocode

HTML markup + FastSpring script setup:

<!-- Display the promo code applied to the current order -->
Applied Promo Code:
<span data-fsc-order-promocode>
  <!-- The applied code (e.g. TENOFF) will be dynamically rendered here -->
</span>

<!-- Load the FastSpring Store Builder script -->
<script
  id="fsc-api"
  src="https://sbl.onfastspring.com/sbl/1.0.3/fastspring-builder.min.js"
  type="text/javascript"
  data-storefront="your-storefront-URL">
</script>

What it does: Displays the promo code currently applied to the order. This value only appears after the buyer has entered a valid code or applied via JavaScript.

What to update:

Replace your-storefront-URL with the full path to a checkout in your store.
Optional: Add a product and apply a promo code (fastspring.builder.promo("TENOFF")) to test this field in your session.

data-fsc-promocode-value

HTML markup + FastSpring script setup:

<!-- Input and button to apply a promo code to the order -->
Coupon Code:
<input type="text" data-fsc-promocode-value placeholder="Enter coupon code" />
<button data-fsc-action="Promocode">
  Apply Coupon
</button>

<!-- Load the FastSpring Store Builder script -->
<script
  id="fsc-api"
  src="https://sbl.onfastspring.com/sbl/1.0.3/fastspring-builder.min.js"
  type="text/javascript"
  data-storefront="your-storefront-URL">
</script>

What it does: Lets the buyer enter and apply a promo code. The data-fsc-action="Promocode" button checks the closest input with data-fsc-promocode-value and applies it to the current session if valid.

What to update:

Replace your-storefront-URL with the full path to a checkout in your store.
Optional: Add a product to the cart and use a valid code (like TENOFF) to see the discount apply.

data-fsc-order-taxType

HTML markup + FastSpring script setup:

<!-- Display the type of tax applied to the order (e.g. VAT, GST) -->
Tax Type:
<span data-fsc-order-taxType>
  <!-- The tax type (e.g. VAT) will be dynamically rendered here -->
</span>

<!-- Load the FastSpring Store Builder script -->
<script
  id="fsc-api"
  src="https://sbl.onfastspring.com/sbl/1.0.3/fastspring-builder.min.js"
  type="text/javascript"
  data-storefront="your-storefront-URL">
</script>

What it does: Displays the type of tax (like VAT or GST) applied to the current order. This value is based on the buyer's country and your store's tax configuration.

What to update:

Replace your-storefront-URL with the full path to a checkout in your store.

data-fsc-taxid-value

HTML markup + FastSpring script setup:

<!-- Allow the buyer to enter a VAT ID to apply tax exemption -->
Tax ID:
<input type="text" data-fsc-taxid-value />

<!-- Button to apply the entered Tax ID -->
<button data-fsc-action="TaxId">
  Apply Tax ID
</button>

<!-- Display the updated order total and tax -->
<br /><br />
Order Total:
<span data-fsc-order-total>
  <!-- The order total with discount (if tax is removed) will render here -->
</span>

<br /><br />
Order Tax:
<span data-fsc-order-tax>
  <!-- The calculated tax amount (e.g. 0.00 after exemption) will render here -->
</span>

<!-- Load the FastSpring Store Builder script -->
<script
  id="fsc-api"
  src="https://sbl.onfastspring.com/sbl/1.0.3/fastspring-builder.min.js"
  type="text/javascript"
  data-storefront="your-storefront-URL">
</script>

What it does: Allows the buyer to enter a VAT or GST ID to remove tax from their order. The data-fsc-taxid-value field works with the TaxId action to apply the exemption if valid.

What to update:

Replace your-storefront-URL with the full path to a checkout in your store.
Set the country to one that collects VAT (e.g. Germany) using fastspring.builder.country("de").
Include at least one product in the cart to trigger tax calculations.

data-fsc-order-tax

HTML markup + FastSpring script setup:

<!-- Display the calculated tax for the order -->
Order Tax:
<span data-fsc-order-tax>
  <!-- The tax amount (e.g. $1.23) will be dynamically rendered here -->
</span>

<!-- Load the FastSpring Store Builder script -->
<script
  id="fsc-api"
  src="https://sbl.onfastspring.com/sbl/1.0.3/fastspring-builder.min.js"
  type="text/javascript"
  data-storefront="your-storefront-URL">
</script>

What it does: Dynamically displays the tax applied to the order. This value updates automatically based on the buyer's country, region, or postal code and reflects VAT, GST, or US sales tax when applicable.

What to update:

Replace your-storefront-URL with the full path to a checkout in your store.

data-fsc-order-taxRate

HTML markup + FastSpring script setup:

<!-- Display the tax rate applied to the order -->
Order Tax Rate:
<span data-fsc-order-taxRate>
  <!-- The tax rate (e.g. 19%) will be dynamically rendered here -->
</span>

<!-- Load the FastSpring Store Builder script -->
<script
  id="fsc-api"
  src="https://sbl.onfastspring.com/sbl/1.0.3/fastspring-builder.min.js"
  type="text/javascript"
  data-storefront="your-storefront-URL">
</script>

What it does: Displays the percentage tax rate applied to the order (such as 7% for US sales tax or 19% for German VAT). FastSpring automatically calculates this value based on buyer location and tax rules.

What to update:

Replace your-storefront-URL with the full path to a checkout in your store.

data-fsc-order-taxValue

HTML markup + FastSpring script setup:

<!-- Display the numeric tax value applied to the order -->
Order Tax Value:
<span data-fsc-order-taxValue>
  <!-- The raw tax amount (e.g. 1.23) will be dynamically rendered here -->
</span>

<!-- Load the FastSpring Store Builder script -->
<script
  id="fsc-api"
  src="https://sbl.onfastspring.com/sbl/1.0.3/fastspring-builder.min.js"
  type="text/javascript"
  data-storefront="your-storefront-URL">
</script>

What it does: Displays the raw tax amount for the order, without currency symbols or formatting. This is useful when you want to use or display tax data in a custom format or logic block.

What to update:

Replace your-storefront-URL with the full path to a checkout in your store.

FAQs

My product directive isn't working. Why?

This usually means the product isn't added to the homepage of the checkout you linked to in data-storefront. Even if the product is in the checkout, it must be available on the homepage for directives to work.

What happens if I don't specify a product path?

If the data-fsc-item-path attribute is missing, the product-level directives will not retrieve data, and the element will remain empty.

How do I test directives before deploying?

Use your browser's developer tools to inspect elements and verify that the directives are pulling the correct data from your FastSpring store.