StoreFront Velocity Receipt Tokens Overview and Accessing Order Item Data
StoreFront Velocity Receipt Tokens
Last Updated: June 25, 2026
Table of Contents
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
$orderobject 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:
Method | Returns | Description |
|---|---|---|
|
| Merchant item ID (SKU) |
|
| Quantity ordered |
|
| Unit cost |
|
| Value of a named item attribute |
|
| Item description |
Looking Up a Specific Item by ID
The Legacy $order.getProductQuantity('SKU') method is not available in StoreFront. To get the quantity for a specific item, loop through $order.getItems() and match on item ID. The pattern below combines the existence check and quantity lookup in a single pass:
#set($itemFound = false)
#set($targetQty = 0)
#foreach ($item in $order.getItems())
#if ($item.getItemId() == 'WB12-100')
#set($itemFound = true)
#set($targetQty = $item.getQuantity())
#end
#end
#if ($itemFound)
<script src="https://example.com/webhook?item=WB12-100&qty=$targetQty"></script>
#end
Important: Use
$targetQtydirectly in URL query strings when the value is an integer. Do not wrap it withformatHelper.urlEncode()inside an HTML attribute — see formatHelper.urlEncode() in Script Attributes below.
formatHelper.urlEncode() in script src Attributes
formatHelper.urlEncode() does not evaluate when placed inside a <script src="..."> attribute value in StoreFront receipt Velocity. The expression renders as a literal string (e.g., qty=${formatHelper.urlEncode($targetQty)}), and the webhook or pixel receives the unexpanded text rather than the actual value.
Does not work:
<script src="https://example.com/webhook?qty=${formatHelper.urlEncode($targetQty)}"></script>
Works — use the variable directly for numeric values:
<script src="https://example.com/webhook?qty=$targetQty"></script>
For integer values such as quantity, no URL encoding is needed. If you need to pass a string value that may contain special characters, pre-compute the encoded value before the HTML tag using #set, then reference the result variable in the attribute:
#set($encodedValue = $someStringVar)
## Note: if formatHelper is unavailable in this context, sanitize the value upstream
<script src="https://example.com/webhook?value=$encodedValue"></script>
Legacy vs. StoreFront Method Comparison
Legacy Method | StoreFront Equivalent | Notes |
|---|---|---|
| Loop + | See example above |
|
| Available in both; same signature |
|
| Available in both; same signature |
|
| Available in both |
|
| Available in both |
|
| Available in both |
|
| 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).
Related Documentation
Velocity Coding Example - Receipt Conditional Text From Item Attribute - Pattern for conditionally rendering content based on item attributes
The StoreFront Template Language - General StoreFront Velocity reference
StoreFront Screen Interfaces - Which objects are available on which screens