Template Reference

Last modified December 15, 2016

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.

Example of the Default Order Receipt with the TEMPLATE command highlighted

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.


Example of the Default Order Receipt template

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

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.

Element Description Example Explanation
{{#each}} Requires an order object reference (e.g. order.items) and a closing {{/each}} tag.

Cycles through all objects of the specified type, processing the contents up to the closing {{/each}} tag for each.
{{#each order.items}}
{{display}}
{{/each}} 
This example loops through each product that was included in the purchase (order.items). Any content included between {{#each order.items}} and {{/each}}, such as the variable {{display}} that renders the product's display name, will be evaluated and processed for each product in the order.
{{#if}}

Conditional evaluation for use in Boolean expressions.

Requires a closing {{/if}} tag.

You can use this with object references to control when certain behavior occurs or when certain content will be included in the messages.

{{#if license}}
{{display}}: {{license}}
{{/if}}

This example, paraphrased from the Default Order Receipt, is found in the context of an {{#each fulfillments}} loop. For each fulfillment action associated with a product, this checks to see whether or not the fulfillment action is a license key.

If the fulfillment action is a license key, the product's display name will be rendered in place of the {{display}} variable, and the license key will be rendered in place of the {{license}} variable.

If the fulfillment action is not a license key, nothing between this {{#if}} and its closing {{/if}} tag will be rendered.
{{#iff}}

Conditional evaluation for use in comparisons, such as checking for a specific string variable or other value and then reacting to the result of that check.

Requires a closing {{/iff}} tag.


An optional {{else}} tag can also be used, to handle the reverse outcome (i.e. when the result of the {{#iff}} evaluation is false.)


You can use this with object references to control when certain behavior occurs or when certain content will be included in the messages.

The following operators are supported for use with {{#iff}}; be sure to include double-quotation marks around the operator in your expression, as in the example shown to the right

== equal to
!= not equal to
< less than
> greater than
<= less than or equal to
>= greater than or equal to

{{#iff product "==" "falcon"}}
{{>falconAP}}
{{else}}
{{>productAP}}
{{/iff}}

This example, which would be implemented in the context of an {{#each order.items}} loop, checks whether the current product path is equal to the string "falcon".

If that expression is true - i.e., when "falcon" is the product path of the current item in the product loop - a custom shared snippet  named falconAP will be inserted.

If that expression is false - i.e., when "falcon" is NOT the product path of the current item in the product loop - a custom shared snippet named productAP will be inserted.

You could also insert text or HTML directly into your comparison, but using shared snippets might be quicker, cleaner, and more efficient. Your shared snippet can include all translations and even other shared snippets.

The above is only one example of how you can use comparisons; another use might be to conditionally suppress or hide certain parts of the email message. You would not even have to use an {{else}} condition in some cases.

Nor is the product loop the only place you can use comparisons like this. This feature allows for a great deal of customization and flexibility. 

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.

Note about variable names and HTML escaping

The double 'Handlebar' format used to insert object reference variables also causes all characters to be HTML escaped. Therefore, if your product or subscription names include certain punctuation, such as a single quote character ('), you should use triple 'Handlebars' instead, to disable the HTML escape functionality.

For example, if your subscription product name has a single quote character, you can change {{subscription.display}} to {{{subscription.display}}} so that the character (') will be rendered rather than the corresponding HTML encoding (&#x27;).

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.

Object Type Description
order.to general email address to which the notification message is being sent
order.replyTo general your reply email address, as configured under Settings > Store Settings >
General > Reply To Email  (typically should be your customer service
address) 
order.language general two-character ISO language code for the language in which the transaction was
processed (e.g. "en") 
order.reference general order reference
order.account.url general URL for the customer-facing Account Management page associated with this customer 
order.changedDisplay general date on which the transaction record was most recently modified, formatted as
MM/DD/YYYY; in the context of the Default Order Receipt notification template,
this will be the order date

example:

03/26/2016 
order.live Boolean indicates whether or not the order was live (as opposed to a test order)
order.currency general 3-character ISO code for the currency in which the transaction was processed
order.total number total price paid by the customer, without currency indicator
order.totalDisplay general total price paid by the customer, formatted to include currency indicator
order.tax number amount of sales tax or VAT paid by the customer (if any), without currency indicator
order.taxDisplay general amount of sales tax or VAT paid by the customer (if any), formatted to include currency
indicator
order.subtotal number order subtotal before sales tax or VAT (if any), without currency indicator
order.subtotalDisplay general order subtotal before sales tax or VAT (if any), formatted to include currency indicator
order.account general account ID of the customer
order.discount number amount of the discount applied to the order (if any), without currency indicator
order.discountDisplay general amount of the discount applied to the order (if any), formatted to include currency
indicator
order.discountWithTax number amount of the discount applied to the order (if any) including any sales tax or VAT,
without currency indicator
order.discountWithTaxDisplay general amount of the discount applied to the order (if any) including any sales tax or VAT,
formatted to include currency indicator
order.invoiceURL general URL for the customer's invoice for this transaction
order.billDescriptor general transaction description that will appear on the customer's payment account

example:

FS * fsprg.com 
order.payment.type general

indicates method of payment used by the customer (e.g. "card")

order.payment.cardEnding general indicates the last four digits of the card number used for the purchase, where
applicable
order.tags general

renders the values for any order-level custom tags that were associated with the
purchase (e.g. for Custom Orders or orders created using POST /orders via the
FastSpring API).

Enter the key name for the tag whose values you want rendered in email messages.

For example, if one or more orders may have a custom tag with a key name of
REFERRALMETHOD, you could render the values for that tag in email messages
by including the following in your notification template:

{{order.tags.REFERRALMETHOD}}

order.customer.company general company name entered by the customer, if any
order.customer.email general

customer's email address

order.customer.first general customer's first name
order.customer.last general customer's last name
order.customer.phone general telephone number entered by the customer, if any
order.address.addressLine1 general customer's address line 1 for orders with a physical product or required
shipping address 
order.address.addressLine2 general customer's address line 2 (if any) for orders with a physical product or required
shipping address 
order.address.city general customer's city for orders with a physical product or required shipping address
order.address.region eneral customer's state, province or region for orders with a physical product or required
shipping address 
order.address.country general customer's country as specified in the address for orders with a physical product or
required shipping address 
order.address.postalCode general customer's postal code for orders with a physical product or required shipping
address 
order.items array

array consisting of various fields of product information for the products that have
been purchased in this transaction

usage example:

{{#each order.items}}
     {{display}}
{{/each}}
 product general  product path for the current order item

only valid in the context of {{#each order.items}} ... {{/each}}
 quantity number  quantity of the current order item that was purchased

only valid in the context of {{#each order.items}} ... {{/each}} 
 display general  display name for the current product

only valid in the context of {{#each order.items}} ... {{/each}}
 subtotal number  subtotal for the current order item
 
only valid in the context of {{#each order.items}} ... {{/each}}
 sku general  sku (if any) from the product record of the current order item

only valid in the context of {{#each order.items}} ... {{/each}} 
 attributes general custom attributes (if any) from the product record for the current order item

Enter the key name from the product's custom attribute that you want rendered,
e.g. as configured under Products > MORE > Custom Attributes > KEY. The
corresponding value will be rendered.

For example, if one or more of your products has a custom attribute with a KEY of
OLDSKUID, and each products has a unique value for that property, you could render
those values in email messages by including the following in your notification template:

{{attributes.OLDSKUID}}

only valid in the context of {{#each order.items}} ... {{/each}} 
 discount number  discount (if any) applied to the current order item, without currency indicator

only valid in the context of {{#each order.items}} ... {{/each}}
discountDisplay general

discount (if any) applied to the current order item, formatted to include currency
indicator

only valid in the context of {{#each order.items}} ... {{/each}}

 subscription.id general  subscription ID (if any) associated with the current order item

only valid in the context of {{#each order.items}} ... {{/each}} 
 coupon general  coupon code of any promotion applied to the current order item

only valid in the context of {{#each order.items}} ... {{/each}} 
fulfillments array

array consisting of various fulfillment-related fields (if any) applicable to the
current product

Your template needs to use a nested loop called 'this' within the {{#each.fulfillments}}
loop, as illustrated here:

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


only valid in the context of {{#each order.items}} ... {{/each}} 

type general type of the current fulfillment action, for the current product

only valid in the context of {{#each fulfillments}}{{#each this}} ... {{/each}}{{/each}}
display general display name indicating the type of the current fulfillment action for the current
product

only valid in the context of {{#each fulfillments}}{{#each this}} ... {{/each}}{{/each}}

example:

for a download, this will render file
for a license key, this will render License Key.
license general

license key (if any) issued for the current fulfillment action, for the current
product

only valid in the context of {{#each fulfillments}}{{#each this}} ... {{/each}}{{/each}}

size number size of the download file associated with the current fulfillment action (if any),
for the current product, in bytes

only valid in the context of {{#each fulfillments}}{{#each this}} ... {{/each}}{{/each}}
file general download URL for the file (if any) associated with the current fulfillment action,
for the current product

only valid in the context of {{#each fulfillments}}{{#each this}} ... {{/each}}{{/each}}
order.support.contactName general your support contact name, as configured under Settings > Store Settings >
Support Contact > Support Contact Name
order.support.contactEmail general your support contact email address, as configured under Settings > Store Settings
> Support Contact > Support Contact Email 
order.isRebill Boolean Boolean value indicating whether or not the transaction was processed as an automatic
rebill on an existing subscription

New orders placed directly by customers will have a value of false for this item.


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.
 

Snippet Variable Description
{{>border-style}} Specifies border width, type and color; this can be used in a border attribute in place of entering inline styling (similar to a class in a style sheet).
{{>font}} Specifies a series of font families; this can be used in a font-family attribute place of a list of font families.
{{>footer}} Provides a block of HTML and CSS, with some translations and other shared snippets, designed to render a professional-looking footer for use at the bottom of your templates.
{{>header}} Provides a block of HTML and CSS, with some translations and other shard snippets, designed to render a professional-looking header for use at the top of your templates.
{{>header-background-color}} Specifies the hex value of a color (#30363d by default) that is used in the {{>header}} snippet, by default, to color the header background; but you can use this in any color attribute in your template, or in another shared snippet.
{{>logo}}

Specifies the URL for a logo file (http://fastspring.com/images/fastspring-orange-white-logo.png by default), which can be used in the src attribute of an img element in your template or in another shared snippet.

Tip

For best results, we recommend using a logo image no wider than approximately 275 pixels. The default logo image is 143 x 35 pixels.
{{>store-title}} A simple string of text that identifies the name of your Store. This is used in the {{>text-header}} snippet by default. The default value is FastSpring Checkout.
{{>table-header-color}} Specifies the hex value of a color (#f5f5f5 by default) that is used in the template of the Default Order Receipt notification and in the {{>footer}} snippet, by default, but you can use this in any color attribute in your template, or in another shared snippet.
{{>text-header}} Provides a block of text designed to render a professional-looking header for use at the top of the Text portions of your templates.
{{>text-footer}} Provides a block of text designed to render a professional-looking footer for use at the bottom of the Text portions of your templates.


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.

    Settings menu with the Customer Notifications tab selected


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

    Customer Notifications tab with the Shared Snippets link highlighted


  3. Click the The ADD SNIPPET button button at the top right-hand corner of the page. The Shared Snippets popup window will appear.

    Shared Snippets popup window
  4. 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.
  5. 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.

    Example of entering a new shared snippet in the Shared Snippets popup window
  6. 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.

    Example of a newly-added shared snippet

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.

Note

The Default Order Receipt notification and some of the shared snippets that are available by default use a variety of translations. Before taking advantage of these and any other translations you may create, the actual translated text needs to be entered in each language supported by your Store.

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.

    Settings menu with the Customer Notifications tab selected

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

    Customer Notifications tab with the Translations link highlighted

    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 (=).

    Example of the Translations page

  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 (}}).

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