Documentation

Managing and displaying receipt data

Transaction receipt data in InStore

InStore makes it easy for retailers to include and format almost any information about the location, customer, cart contents, financial detail, and more on their customer-facing receipts.

Through a receipt callback, InStore can handle externally maintained data that the retailer has selected to include on the receipt. This can be merchandise customization, such as special orders relating to manufacturing, assembly, delivery, and other information stored beyond the confines of the cart.

To understand what data is available for inclusion on receipts, access the unstructured JSON schema file on the commercetools GitHub repository for the Receipt Print Server.

Receipt processing

To generate accurate receipts to retailer specifications, InStore Receipt Print Server first retrieves and transforms the necessary data in JSON format. It then applies the correct retailer-specified template, which consists of both Handlebars and ReceiptLine markup. InStore receipt formulation adheres to the Open Foodservice System Consortium standard.

The result is merged through the Handlebars engine, where Handlebars tags are replaced with actual data. The markup and data then pass to the Receiptline engine, which turns the markup in the formatted receipt into code that:

  • renders receipt data on-screen as a user-visible scalable vector graphic (SVG) image
  • presents printer-readable code to the in-store printer so that customers can receive a hard copy. Printer readability is accomplished with an environment variable that is required in every local environment
  • can be accessed by retailers who want to send receipts through their own SMS or email channels

List of transaction receipts

These are the customer-facing receipts that are generated by InStore transactions:

Receipt templates

A set of base receipt templates in English is provided automatically with InStore. Plain text appears on the receipt and requires translation for non-English locales. For more information about building and applying custom template sets, see Receipt template sets.

Future enhancements to the commercetools-provided base template set will apply only to that set. Customized template sets cannot receive enhancements. To benefit from improvements, retailers must make manual changes to custom templates or revert to the base set.

Helpers unique to InStore

For information about standard helpers, see Receipt helpers. Helpers specific to the InStore colleague app appear in the sample receipt templates and include the following:
  • Include the Location ID: Our default receipt displays the Location Name. You can also display the store's Location ID (originally assigned on the Location detail page of the Administrator Portal) on the receipt. The Location ID is also used in each InStore transaction number. To display it, include the variable that is shown in this example: Branch: {{location.location_ID}}
  • Display a Reprinted Receipt label: You can add the words "Reprinted Receipt" to a receipt that was produced via the Reprint Receipt menu option. Insert the following block in the regular Sales or Refund receipt template; it will not print on original receipts, only reprints. Translate only the text shown within asterisks (the asterisks are optional). {{#if reprint}}***Reprinted Receipt***{{/if}}
  • Display Cash Rounding label and amount: In environments where cash rounding is activated, you can set up the receipt to include the amount by which the cash paid or refunded was rounded up or down. Insert the following block in the regular Sales or Refund template; it will not print for tender types other than Cash. Translate only the text "cash rounding." {{#if type.cash}}{{indent 2}}cash rounding: {{#rightjustify}}{{cash.roundedRemainder}}{{/rightjustify}}{{/if}}
  • Make conditional statements based on numeric values: InStore offers several operators that can be used to evaluate amounts and control receipt behavior accordingly. The operators are if_gt (if greater than), if_gte (if greater than or equal to), if_lt (if less than), if_lte (if less than or equal to), if_eq (if equal to), or if_ne (if not equal to). {{#if_gte amount 10000}}{{A}} {{else}}{{B}}{{/if_gte}} Where A and B must be substituted by actions you have programmed. For example, if the customer spends at least 100.00, print a coupon for 5.00 (action A). If the customer did not spend the threshold amount, print an advertisement for an upcoming promotion (action B).
  • formatcurrency prefix indicates that the subsequent number (object) should be formatted as currency for the region. To display a currency symbol such as $ or £, you must add it manually as plain text.
  • Include all data provided by Payment Provider (Adyen, etc.): An attribute called receiptData contains all the data fields from the receipt that the Payment Provider would have created. Retailers are invited to harvest information from this data blob.

Non-customer-facing receipts

InStore produces printed receipts for the following Cash Management activities:

  • Bank Deposit
  • Cash Count
  • Pay In
  • Pay Out
  • Safe Deposit
  • Transfer In
  • Transfer Out

Because most retailers decide not to customize these, details about formatting internal-only receipts are not specified in this documentation. However, the same formatting rules and methods apply to these receipts as to transaction receipts. If you have questions about customizing these, contact your commercetools contact person.