Documentation

Helpers for receipt templates

View all the available helpers you can use in your receipt templates.

You can use both built-in Handlebars.js helpers and custom receipt-specific helpers.

Handlebars.js helpers

Basic block helpers

#each

The #each helper iterates over an array or object properties.

{{#each items}}
  {{@index}}:
  {{this.name}}
  -
  {{this.price}}
{{/each}}

Special variables available inside #each:

  • @index: Zero-based index of the current item in the array
  • @key: Current property name when iterating over object properties
  • @first: True if this is the first item
  • @last: True if this is the last item
  • this: References the current item
  • ../: Access parent context

#if

The #if helper conditionally renders a property when the condition is truthy.

{{#if customer.name}}
  Welcome,
  {{customer.name}}!
{{else}}
  Welcome, Guest!
{{/if}}

#unless

The #unless helper is the inverse of the #if helper and renders the property when condition is falsy.

{{#unless paid}}
  Payment Required
{{/unless}}

#with

The #with helper creates a new context scope.

{{#with customer}}
  {{name}}
  -
  {{email}}
{{/with}}

Currency formatting

formatCurrency

The #formatCurrency helper formats monetary values using Dinero.js with the configured currency settings. All currency values are handled using Dinero.js for precise calculations.

{{formatCurrency amount 'numeric'}}
{{! Formats without currency symbol }}
{{formatCurrency amount}}
{{! Formats with currency symbol }}

Parameters for this helper include the following:

  • amount: A Dinero.js object representing the monetary value.
  • format - Optional: Use numeric for amount-only display without a currency symbol.

Item grouping

groupByFacet

The #groupByFacet helper groups line items based on a specified facet and calculates totals for each group.

{{#groupByFacet line_items 'facetName'}}
  {{groupKey}}
  ({{totalQuantity}}
  items) subtotal:
  {{formatCurrency subtotal}}
{{/groupByFacet}}

Available properties include the following:

  • groupKey: The facet value for this group
  • totalQuantity: Total number of items in the group
  • subtotal: Dinero.js object representing the group's total value
  • items: Array of items in the group

Printer commands

barcode

The #barcode helper generates commands to print a barcode. It generates a Code 128 barcode with human-readable interpretation (HRI).

{{barcode value}}

Parameters for this helper include the following:

  • value: The data to encode in the barcode

Text formatting

truncate

The #truncate helper truncates text to a specified length, ending at a word boundary with ellipsis. This helps ensure that text fits within the printer's width dimensions.

{{truncate description 20}}

Parameters for this helper include the following:

  • str: The string to truncate
  • len: Maximum length before truncation

Custom conditional helpers

Conditional helpers can be nested.

if_gt (greater than)

The #if_gt helper conditionally renders content if the value is greater than the threshold.

{{#if_gt value threshold}}
  Content shown if value > threshold
{{/if_gt}}

if_gte (greater than or equal to)

The #if_gte helper conditionally renders content if the value is greater than or equal to the threshold.

{{#if_gte value threshold}}
  Content shown if value >= threshold
{{/if_gte}}

if_lt (less than)

The #if_lt helper conditionally renders content if the value is less than the threshold.

{{#if_lt value threshold}}
  Content shown if value
{{/if_lt}}

if_lte (less than or equal to)

The #if_lte helper conditionally renders content if the value is less than or equal to the threshold.

{{#if_lte value threshold}}
  Content shown if value
{{/if_lte}}

if_eq (equal)

The #if_eq helper conditionally renders content if the value is equal to the threshold.

{{#if_eq value threshold}}
  Content shown if value === threshold
{{/if_eq}}

if_ne (not equal)

The #if_ne helper conditionally renders content if the value is not equal to the threshold.

{{#if_ne value threshold}}
  Content shown if value !== threshold
{{/if_ne}}

Example of built-in and custom helpers:

The following is an example that combines both built-in and custom helpers:

{{! Logo at the top }}
{{logo 1 1}}


{{#if store.name}}
  {{store.name}}
{{else}}
  Default Store
{{/if}}


{{! Group items by product type }}
{{#groupByFacet line_items 'productType'}}
  ===
  {{groupKey}}
  ===


  {{#each items}}
    {{! Show item number for non-first items }}
    {{#unless @first}}
      {{@index}}.
    {{/unless}}
    {{truncate description 20}}


    {{! Format price based on amount }}
    {{#if_gt price.amount 10000}}
      **{{formatCurrency price}}**
    {{else}}
      {{formatCurrency price}}
    {{/if_gt}}
  {{/each}}


  {{#if_gt totalQuantity 1}}
    Group Total ({{totalQuantity}}
    items):
    {{formatCurrency subtotal}}
  {{/if_gt}}
{{/groupByFacet}}


{{! Only show barcode if order number exists }}
{{#with order_number}}
  {{barcode this}}
{{/with}}

Best practices

We recommend you follow the following best practices for your receipts:

  • Truncate long text to prevent line wrapping.
  • Use conditional helpers to handle edge cases.
  • Group related items using the groupByFacet helper for better organization.
  • Use built-in context variables, such as @index or @first for more control.
  • Use relative paths, ../ when accessing parent context inside blocks.
  • Combine built-in and custom helpers for complex logic.
  • Use the appropriate currency formatting based on display context.

Troubleshooting

If you are having issues with your receipt templates, try the following common fixes:

  • If the currency values appear incorrect, make sure you're passing Dinero.js objects.
  • For nested contexts, verify path references are using ../.
  • If grouping isn't working, check that facet names match exactly.
  • For printer commands, verify the printer type configuration.