Template Reference

Overview

The Customer Notifications feature allows you to customize the email messages that will automatically be sent to customers when certain events occur. For example, you can customize the message that will be sent to customers after each successful purchase.

The content of the messages sent via a customer notification is generated according to the content of the notification's template. To begin editing the template for a notification, click the TEMPLATE command as shown below.



You can edit the subject line that will be used for messages sent via the notification by making changes to the Subject field of the template, and you can edit the body of the messages by modifying the HTML and / or Text tabs of the template's message body area.

If you make a mistake entering one of the template elements such as a variable for an order object or some invalid HTML code, the green Valid indicator next to the HTML tab will change to a red Invalid indicator and you will not be able to save your changes. In the example below, the shared snippet {{header2}} is included, but that is not a valid tag because no such shared snippet has been defined.
 

The Test link lets you send a test message to a specified email address with your current changes before saving them, so you can see how the messages will look without committing the changes to be used for live customer orders. If you send a test message, be sure to review it carefully in your email client before you click  to commit your changes.


 

Each notification's template is made of basic HTML and CSS code, combined with certain other elements that can be used to render order-specific data and streamline the process when editing a template to customize the messages.

Each of those other elements can be thought of as belonging to one of four classifications:

• logical evaluation elements
• object references
• shared snippets
• translations

Logical evaluation elements

Logical evaluation elements let you display certain sections of content within a notification conditionally. For example, you can include text, HTML or shared snippets conditionally based on whether or not a certain product is in the order.

Here are examples of some commonly-used logical evaluation elements.

back to list

Object references

References to order elements such as the list of products that have been ordered, the customer's name and e-mail address, license keys that have been generated and much more can be included in the notification. This is accomplished by inserting a variable consisting of curly brackets and the object's name into your template.

For example, including the variable {{order.reference}} in the body of your notification will render the order reference (order number) in the email messages. The key to taking advantage of object references is to know the correct variable names.

Many of the objects are subordinate to other objects, meaning that you have to include the name of the containing object as well as the name of the actual field you want in a single variable in order for it to work correctly. For example, the correct variable name for the order's subtotal is {{order.subtotal}} as opposed to just {{subtotal}}. As another example, the correct variable name for your customer support email address as configured in your Store is {{store.support.email}}. Entering only {{support.email}} will not work.

Because the JSON data output for an order event uses arrays to group together fields that may have more than one value in a single purchase transaction (such as different product names for orders with more than one item purchased), certain variables can only be included inside the context of an {{#each}} loop. For example, since you do not know in advance which specific products will be included in any given purchase transaction, the {{#each.order.items}} element is needed to "loop" through all products that were purchased. Inside that loop, it is not necessary to specify the containing array objects in your variable names. Each variable you include in the loop will be evaluated once, separately, for each item in the array (e.g. order items). For example, between {{#each.order.items}}and its corresponding {{/each}}, you can include things like {{display}} to render the display names of all products that were purchased, like this:

{{#each.order.items}}
     {{display}}
{{/each}}

The following table identifies some of the order objects that can be included in your notification template.

{{#each order.items}}
     {{display}}
{{/each}}

{{#each fulfillments}}
     {{#each this}}
          ((your fulfillment variables go here))
     {{/each}}
{{/each}} 

back to list
 

Shared Snippets

Shared snippets are self-contained, commonly-used elements of notifications that can be used by more than one notification. For example, inserting the {{>header}} tag in the body of your notification will cause the entire contents of the {{>header}} snippet to be rendered in place of the {{>header}} tag. This allows you to create a single message header with images, links, company information, etc., that can be used in multiple notification templates without having to recreate it in each one. Later on, if you need to make changes to the header, you can modify the shared snippet and all notifications that use that snippet will automatically use the current version of it.

In addition to being useful in your notification's template, shared snippets can also be used inside other shared snippets. They are defined on the Shared Snippets page of the Customer Notifications tab.

The following shared snippets are available by default.
 

Shared snippets are designed to be customized by you.  You can use the EDIT command below any snippet to modify the contents (or even the name) of that snippet, or use the DELETE command to permanently delete a snippet (but please be sure you have identified all templates and other shared snippets that use the snippet you want to delete before doing so).

To create a new shared snippet

1. From the Dashboard, select the Settings menu and then click the Customer Notifications tab.
   
   
2. Click the Shared Snippets option on the left-hand side of the page.
   
   
3. Click the  button at the top right-hand corner of the page. The Shared Snippets popup window will appear.
4. 
5. In the Snippet Tag field, enter the name you want to use to reference this snippet elsewhere (i.e. in notification templates and / or in other snippets). You do not need to enter the curly brackets {{}} or the > symbol; just enter a name with only letters, numbers and dashes (no punctuation). The curly brackets and the > symbol will automatically be added to the name you have entered once you save the snippet.
6. In the Snippet Text/HTML Value field, enter or paste in the contents of the snippet - that is, the value that will replace the Snippet Tag entered above when notification templates or other snippets are processed. In the example below, we are creating a snippet that will insert a new paragraph containing link to our blog, with a custom translation as a call to action.
   
   
7. Click ADD to save and finish adding the new snippet. A new tile for the new snippet will appear on the list of shared snippets.
   
   

back to list

Translations

Translations work similarly to shared snippets in that you can enter a placeholder variable in your notification's template that will automatically be replaced by another value defined elsewhere when the email messages are sent. In this case, there is a special set of snippets defined on the Translations page of the Customer Notifications tab. The customer's language used for the order will automatically be evaluated, and the corresponding translation will be rendered. For example, if you include {{translate "Total"}} in the body of your notification and a customer processes an order with Spanish selected, then the value for the Total= entry found on the Spanish page of the translations will automatically be rendered in the email message.

To enter translated text for existing translation words and phrases

1. From the Dashboard, select the Settings menu and then click the Customer Notifications tab.
   
   

2. Click the Translations option on the left-hand side of the page.
   
   
    

    Note

   The red exclamation mark next to the Translations option indicates that there are words and / or phrases awaiting translation text in one or more languages.
3. On the Translations page, select the language for which you want to enter translations, on the left-hand side of the page. Then, simply click in the text area and begin entering translations for each word or phrase following the equals sign (=).
   
   
4. When you are finished entering translations for the words and phrases in each supported language, click .

Adding new words or phrases for translation

When you are ready to add new words or phrases to be translated, so that you can use a single common variable in all notification templates and shared snippets, there is no need to go through any special process of adding items to the list. Instead simply, enter {{translate and then type the word or phrase you want to translate, between double quotation marks (") and followed by two closing curly brackets (}}).

When you are ready to add new words or phrases to be translated, so that you can use a single common variable in all notification templates and shared snippets, there is no need to go through any special process of adding items to the list. Instead simply, enter {{translate and then type the word or phrase you want to translate, between double quotation marks (") and followed by two closing curly brackets (}}).

For example, if you want to set up translations for the phrase "Be sure to check out our blog at", then inside the notification template or the shared snippet where this phrase will be used, enter the following:

{{translate "Be sure to check out our blog at"}}

This syntax tells the notification system to look for translations on the Translations page. As soon as you save the notification template or shared snippet you are working on, the new translation will appear in the list on the Translations page. That is all you have to do to add new words or phrases to the list - there is nothing to it. When you are ready, you can return to the Translations page and enter translations for the new phrase in each supported language.

The following brief video illustrates the process of creating a new translation that will be used in a shared snippet. Notice that there are a total of 6 translations available at the start of the video, and after creating the shared snippet with a new translation phrase, there are 7 translations available. We then enter the translated text for the new phrase in Spanish, and save our work.

You can edit any translation by simply selecting the language on the left, clicking in the text area, and making your changes. You can even delete translations via this method as well (but please be sure you know all of the shared snippets or places in a notification that use the translation before doing so).

back to list