Results in FastSpring Documentation:

Template Reference

Overview

This article provides additional details about modifying the templates used for Customer Notifications.

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

The content of the messages sent via a customer notification is generated based on 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 used for messages sent via the notification by making changes to the Subject field of the template. You can edit the body of the messages by modifying the HTML and 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 changes to a red Invalid indicator. You cannot save your changes while the Invalid indicator appears. In the example below, the shared snippet {{header2}} is included in the template. However, that is not a valid tag because no such shared snippet has been defined in this example.

The Test link lets you send a test message to a specified email address with your current changes before saving them. Using the Test link allows you to 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 consists of basic HTML and CSS code, combined with certain other elements. You can use these proprietary elements to render order-specific data and streamline the process when editing a template to customize the messages.

You can think of each of those other elements as belonging to one of four classifications:

Logical Evaluation Elements
Object References
Shared Snippets
Translations

Logical Evaluation Elements

Logical evaluation elements let you display specific sections of content within a notification conditionally. For example, you could include text, HTML, or shared snippets conditionally based on whether or not a particular 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.

This example loops through each product 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, is evaluated and processed for each product in the order.

{{#if}}

Conditional evaluation for use in Boolean expressions.

This element requires a closing {{/if}} tag.

You can use this with object references to control when specific behavior occurs or when certain content appears 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 is rendered in place of the {{display}} variable, and the license key is rendered in place of the {{license}} variable.

If the fulfillment action is not a license key, nothing between this {{#if}} and its closing {{/if}} tagis 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.

You can optionally use an {{else}} tag 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 specific behavior occurs or when certain content appears 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

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

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

If that expression is false - i.e., when "example1" is NOT the product path of the current item in the product loop - a custom shared snippet named productAP is 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.

Tip

The above is only one example of how you can use comparisons; another use might be to suppress or hide certain parts of the email message conditionally. 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

You can include references to order or subscription elements in the notification. The following are some examples of elements you can include:

the list of products in an order
the customer's name and email address
license keys issued for an order

To inject these references into the template, insert a variable consisting of curly brackets and the object's name. For example, including the variable {{order.reference}} in the body of your notification renders 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 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 (').

Many of the objects are subordinate to other objects. Therefore, 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 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}} does not work.

The JSON data output for an order event uses arrays to group fields that may have more than one value in a single purchase transaction. For example, since an order may include more than one product, the system uses an "items" array to group all products in the order record. As a result, you can only include certain variables 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:

The following table identifies some of the order objects that you can include 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	the 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 is the order date example: 06/26/2020
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	the 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 the 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 to appear 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	general	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 to appear, e.g., as configured under Products > More > Custom Attributes > Key. The corresponding value is rendered in the email messages. For example, if one or more of your products has a custom attribute with a Key of OLDSKUID and each of your 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}} For 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	A Boolean value indicating whether or not the transaction was processed as an automatic rebill on an existing subscription New orders placed directly by customers 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 causes the entire contents of the {{>header}} snippet to be rendered in place of the {{>header}} tag. This method allows you to create a single message header with images, links, and company information. You can then use that header 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. All notifications that use that snippet will automatically use the current version of it.

In addition to your notifications' templates, you can also use shared snippets inside other shared snippets. You define shared snippets on the Shared Snippets page of the Customer Emails tab.

The following shared snippets are available by default.

Snippet Variable	Description
{{>border-style}}	Specifies border width, type, and color; you can use this 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; you can use this 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 shared 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. You can also use this in any color attribute in your template, or another shared snippet.
{{>logo}}	Specifies the URL for a logo file (http://fastspring.com/images/fastspring-orange-white-logo.png by default). You can use this 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 snippet appears within 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 the {{>footer}} snippet, by default. You can also 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. The Delete command permanently deletes a snippet. (Please be sure you have identified all templates and other shared snippets that use the snippet you want to delete before deleting it).

To Create a New Shared Snippet

From the FastSpring App, select the Settings menu and then click the Customer Emails tab.
Click the Shared Snippets option on the left-hand side of the page.
Click the button at the top right-hand corner of the page. The Shared Snippets popup window appears.
In the Snippet Tag field, enter the name you want to use to reference this snippet elsewhere (i.e., in notification templates and 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 are automatically added to the name you have entered when you save the snippet.
In the Snippet Text/HTML Value field, enter or paste in the contents of the snippet. That is, enter 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 inserts a new paragraph containing a link to our blog, with a custom translation as a call to action.
Click Add to save and finish adding the new snippet. A new card for the new snippet appears 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 FastSpring sends the email messages. In this case, there is a particular set of snippets defined on the Translations page of the Customer Emails tab. The customer's language used for the order is automatically evaluated, and the corresponding translation is automatically rendered. For example, suppose you include {{translate "Total"}} in the body of your notification. If a customer processes an order with Spanish selected, 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 for which FastSpring has supplied the translated text. If you create any additional translations, be sure to enter the actual translated text in each language as needed.

To Enter Translated Text for Existing Translation Words and Phrases

From the FastSpring App, select the Settings menu and then click the Customer Emails tab.
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 phrases awaiting translation text in one or more languages.
On the left-hand side of the Translations page, select the language for which you want to enter translations. Then, simply click in the text area and begin entering translations for each word or phrase following the equals sign (=).
After 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, there is no need to go through any special process of adding items to the list of translations. 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, suppose you want to set up translations for the phrase "Be sure to check out our blog at." To do this, enter the following inside the notification template or the shared snippet where this phrase is to appear:

{{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. 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 for use in a shared snippet. Notice that at the beginning of the video, there are a total of eight phrases that need translations for the Spanish language. After creating the shared snippet with a new translation phrase, nine phrases need translations in Spanish. We then enter the translated text for the new phrase in Spanish and save our work.

You can edit any translation by merely 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. (Please be sure you know all of the shared snippets or places in a notification that use the translation before deleting it).

back to list

Try FastSpring

Get a free account and see why FastSpring is the ecommerce partner of choice for software providers around the world. Try our full-service ecommerce solution today to unlock revenue growth for your online company.

Create Free Account Get A Demo

Copyright © 2006-2020 Bright Market, LLC dba FastSpring. 801 Garden St., Santa Barbara, CA 93101 Bright Market LLC dba FastSpring Limited. 2 Minton Place, Victoria Road, Bicester, England, OX26 6QB FastSpring B.V. Strawinskylaan 3101 Tenant B.V. 1077 ZX Amsterdam, Netherlands | All rights reserved. Privacy Policy | Terms of Use