Documentation

Create a receipt template

Learn how to create a receipt template using Handlebars and ReceiptLink markup.

Receipt templates are created using two key technologies:

  1. Handlebars: accesses and formats transaction data.
  2. ReceiptLine: controls the visual layout and formatting of the receipt. For more information about ReceiptLine, see the official specification.

The receipt is created in two stages:

  1. Your template is processed with Handlebars to insert all the transaction data.
  2. The resulting document is formatted using ReceiptLine for final printing.

For information about the JSON data fields you can use in your receipt templates, see Data fields for receipt templates.

Available transaction data

Your template can access the following details about a transaction:

Basic transaction data

  • {{timestamp}}: timestamp of the transaction
  • {{timestamp_formatted}}: formatted date and time of the transaction
  • {{order_number}}: unique transaction reference
  • {{workstation_id}}: workstation identifier
  • {{sequence_number}}: sequential transaction number

Customer data

  • {{customer.first_name}}: first name
  • {{customer.last_name}}: surname
  • {{customer.company}}: company name
  • {{customer.account_number}}: account number

Location data

  • {{location.location_name}}: location name
  • {{location.address_line_1}}: first line of the location's address
  • {{location.city}}: city of the location's address
  • {{location.state}}: state of the location's address
  • {{location.telephone_number}}: telephone number of the location

Line item data

Access line items using the {{#each line_items}} helper.

{{#each line_items}}
  {{description}}
  {{quantity}}
  {{formatCurrency price}}
{{/each}}

Payment data

  • Access payment data using the {{#each payments}} helper.
  • Access refund data using the {{#each refunds}} helper.

For a full list of helpers you can use in your receipt templates, see Helpers for receipt templates.

Format your receipt templates with ReceiptLine

Use the following ReceiptLine formatting for your receipt templates:

Basic layout

  • Use | to separate columns.
  • Use - for horizontal lines.
  • Use = for paper cuts.

For example:

Store Name
-----------------
|Item|Qty|Price|
-----------------

Column width

Set column widths using the width property—for example:

{width:*,2,10}  <!-- Dynamic, 2 chars, 10 chars -->
Item Name | 2 | 10.00

Text formatting

Format text using the following:

  • Use ^ to enlarge text.
  • Use " to emphasize text.
  • Use _ to underline text.
  • Use ~ for spaces in text.

For example:

^Welcome^
"Total:" _10.00_

Common patterns of receipt formatting

Header section

The following example shows a common pattern for the header section of a receipt template:

^{{location.location_name}}^
{{location.address_line_1}}
{{location.city}},
{{location.state}}
--------------------------------- Order:
{{order_number}}
Date:
{{timestamp_formatted}}

Item list with totals

The following example shows a common pattern for an item list with totals of a receipt template:

{width:*,2,10}
{{#each line_items}}
  {{description}}
  |{{quantity}}|{{formatCurrency price}}
{{/each}}
--------------------------------- {width:*,20} ^Total:|^{{formatCurrency total}}

Payment section

The following example shows a common pattern for the payment section of a receipt template:

{width:*,20}
{{#each payments}}
  {{type}}|{{formatCurrency amount}}
{{/each}}

Best practices for receipt templates

  • Start simple:

    • Begin with a basic layout and gradually add complexity.
    • Test your templates frequently with sample data.

  • Use proper spacing:

    • Leave empty lines between sections.
    • Use horizontal lines to separate content areas.

  • Mind your widths:

    • Test how text is displated with long item descriptions.
    • Use {width:*} for dynamic columns.
    • Set fixed widths for numbers and quantities.

  • Format numbers consistently:

    • Use the formatCurrency helper for all monetary values.
    • Align numeric columns to the right.

  • Handle edge cases:

    • Include conditional logic for optional fields.
    • Provide fallbacks for missing data.

  • Group related items:

    • Use groupByFacet for organized displays.
    • Consider separate sections for different item types.

Example receipt template

This example demonstrates a full-featured receipt template that includes:

  • Store branding with a logo
  • Location information
  • Transaction details
  • Line items with modifiers and attributes
  • Payment processing details including card information
  • VAT summary
  • Reprint handling
{{logo 32 32}}
{align:center}
{{location.description}}
{{location.address_line_1}}{{#if
  location.address_line_2
}}\n{{location.address_line_2}}{{/if}}
{{location.city}}
{{location.state}}
{{location.postal_code}}
{{location.telephone_number}}


{{#if reprint}}
  {align:center} ^^^*** Reprinted Receipt ***
{{/if}}


{align:left} |Date: |{{timestamp_formatted}}
|Workstation: |{{workstation_id}}
|Cashier: |{{user_id}}
|Transaction #: |{{order_number}}
|VAT ID: |{{tax_id}}


{align:center}
{{barcode order_number}}


{{#each line_items}}
  {width:30,12,*; align:left} |{{truncate description 28}}
  |
  {{formatCurrency extended_price}}|
  {{truncate tax_code 3}}
  {width:16,20,4; align:right}
  {{#if quantity}}{{quantity}}{{else}}1{{/if}}
  @
  {{formatCurrency price}}


  {{#each price_modifiers}}
    |
    {{description}}
    | ({{formatCurrency amount}})|
  {{/each}}


  {width:16,20,4; align:right}
  {{#each attributes}}
    |
    {{label}}: |
    {{value}}|
  {{/each}}
{{/each}}


{width:*; align:center} --- {width:20,*; align:left} ^^^Total: | ^^^{{formatCurrency
  total
}}


{width:20,*; align:right}
{{#each payments}}
  |^{{type}}: |
  {{formatCurrency amount}}


  {{#if charge_card}}
    {{#if charge_card.additional_data}}
      {{#if charge_card.additional_data.receiptData}}
        {width:16,20; align:right} |Card: |
        {{charge_card.additional_data.receiptData.pan}}
        |PAN seq: |
        {{charge_card.additional_data.receiptData.panSeq}}
        |Pref. name: |
        {{charge_card.additional_data.receiptData.preferredName}}
        |Card type: |
        {{charge_card.additional_data.receiptData.cardType}}
        |Payment method: |
        {{charge_card.additional_data.receiptData.paymentMethod}}
        |Payment variant: |
        {{charge_card.additional_data.receiptData.paymentMethodVariant}}
        |Entry mode: |
        {{charge_card.additional_data.receiptData.posEntryMode}}
        |AID: |
        {{charge_card.additional_data.receiptData.aid}}
        |MID: |
        {{charge_card.additional_data.receiptData.mid}}
        |TID: |
        {{charge_card.additional_data.receiptData.tid}}
        |PTID: |
        {{charge_card.additional_data.receiptData.ptid}}
        |Auth. code: |
        {{charge_card.additional_data.receiptData.authCode}}
        |Response code: |
        {{charge_card.authorization_response_code}}
        |Tender: |
        {{charge_card.additional_data.receiptData.txRef}}
        |Reference: |
        {{charge_card.additional_data.receiptData.mref}}
        |Type: |
        {{charge_card.additional_data.receiptData.txtype}}
        |^TOTAL: |
        {{formatCurrency charge_card.additional_data.receiptData.totalAmount}}
      {{/if}}{{else}}
      {width:24,20; align:right} |card number: |
      {{charge_card.last4}}
      |account type: |
      {{charge_card.brand}}/{{charge_card.account_type}}
      |application name: |
      {{charge_card.application_preferred_name}}
      |AID: |
      {{charge_card.dedicated_file_name}}
      |ARC: |
      {{authorization_response_code}}
    {{/if}}{{/if}}


  {{#if gift_card}}
    {width:16,20; align:right} |card number: | *{{gift_card.last4}}
    |card type: |
    {{gift_card.type}}
  {{/if}}


  {{#if wallet}}
    {width:16,20; align:right} method:
    {{wallet.method}}
    |transaction id: |
    {{wallet.transaction_id}}
    |merchant id: |
    {{wallet.merchant_id}}
    |terminal id: |
    {{wallet.terminal_id}}
  {{/if}}
{{/each}}


{width:*; align:center} ^VAT Summary {width:10,12,12,*} Code | Rate| Net| VAT
{{#each tax_summary}}
  {{code}}
  |
  {{tax_rate}}|
  {{formatCurrency total_net}}|
  {{formatCurrency total_tax}}
{{/each}}


---


{{#if reprint}}
  {width:*; align:center} ^^^*** Reprinted Receipt ***
{{/if}}


{width:*; align:center} ^^Thank you! Come again!

Troubleshooting common receipt template issues

  • If the column alignment is off:

    • Check your width properties.
    • Verify column separator placement.
    • Ensure consistent use of spaces.

  • If data isn't displaying as expected:

    • Verify the field names in your template.
    • Check for typos in helper names.
    • Ensure proper closing of blocks.

  • If formatting isn't applying as expected:

    • Verify your ReceiptLine syntax.
    • Check for proper escape sequences.
    • Ensure properties are properly closed.