Skip to main content
How-to

StoreFront Velocity Receipt Tokens

Last Updated: June 25, 2026

Table of Contents​

  1. Overview

  2. The $order Object in Receipt Templates

  3. Iterating Order Items

  4. Looking Up a Specific Item by ID

  5. formatHelper.urlEncode() in script src Attributes

  6. Legacy vs. StoreFront Method Comparison

  7. Troubleshooting

  8. Related Documentation

Overview​

StoreFront Checkout receipt templates support Velocity templating. The $order object is available exclusively on the receipt screen — it is not present in catalog or pre-receipt checkout screens.

This document covers how to access order item quantities and other item properties in StoreFront receipt Velocity, and how Legacy convenience methods map to their StoreFront equivalents.

The $order Object in Receipt Templates​

The $order object is injected into the Velocity context only on the receipt screen. It is available in receipt snippet files located at:

Editor/themes/<ThemeName>/theme/snippets/receipt-*.vm

Important: The $order object is not available in checkout, catalog, or any pre-receipt template. Attempting to use it outside the receipt context will produce no output.

Iterating Order Items​

To access item-level data, call $order.getItems(), which returns a list of OrderItem objects. Iterate with #foreach:

#foreach ($item in $order.getItems())
  Item ID: ${item.getItemId()}
  Quantity: ${item.getQuantity()}
  Cost: ${item.getCost()}
#end

Key methods on each OrderItem:

Legacy MethodStoreFront EquivalentNotes
$order.getProductQuantity('SKU')Loop + item.getQuantity()See example above
$order.isPurchased('SKU')$order.isPurchased('SKU')Available in both; same signature
$order.getItems()$order.getItems()Available in both; same signature
$item.getQuantity()$item.getQuantity()Available in both
$item.getItemId()$item.getItemId()Available in both
$item.getCost()$item.getCost()Available in both
$item.getAttributeValue("name")$item.getAttributeValue("name")Available in both

Note: If a Legacy method you relied on is not listed here, it may not be available in StoreFront. Contact support with the specific method name for confirmation.

Troubleshooting​

Conversion pixel or webhook URL not firing on receipt​

Symptoms: A tracking request, webhook, or pixel embedded in a receipt snippet produces no output or the destination server receives no request.

Root Cause: The Velocity code references a method not available in the StoreFront receipt context (such as $order.getProductQuantity()), causing the template to render an empty string for that token. If the token is used in a URL, the URL may be malformed or the quantity value absent.

Diagnosis: Check whether the rendered HTML in the receipt page source contains the expected URL with the quantity value. An empty or missing value indicates the Velocity method returned null or does not exist in this context.

Solution: Replace the Legacy method with the $order.getItems() loop pattern described in Looking Up a Specific Item by ID.

Server receives literal ${formatHelper.urlEncode(...)} instead of a value​

Symptoms: The webhook or pixel fires successfully, but the server receives the raw Velocity expression as a string (e.g., qty=${formatHelper.urlEncode($targetQty)}) rather than the actual number.

Root Cause: formatHelper.urlEncode() does not evaluate inside an HTML attribute value (such as <script src="...">) in the StoreFront receipt Velocity context. The expression is passed through as literal text.

Diagnosis: Add a debug comment immediately before the <script> tag to confirm the variable itself is resolving correctly:

<!-- DEBUG: targetQty=$targetQty -->
<script src="https://example.com/webhook?qty=${formatHelper.urlEncode($targetQty)}"></script>

If the debug comment shows a correct numeric value but the server still receives a literal string, the issue is formatHelper.urlEncode() failing to evaluate in the attribute context.

Solution: For integer values, use the Velocity variable directly — no encoding is needed:

<script src="https://example.com/webhook?qty=$targetQty"></script>

$order is null or produces no output outside the receipt​

Symptoms: $order references in catalog or checkout templates produce nothing.

Root Cause: $order is only injected into the Velocity context on the receipt screen.

Solution: Move the template logic to a receipt snippet file (receipt-*.vm).

Was this page helpful?