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
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. |
{{#each order.items}} |
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. |
{{#if license}} |
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. | ||||||||||||
{{#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.
|
{{#iff product "==" "example1"}} |
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. 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. |
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
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:
{{#each.order.items}}
{{display}}
{{/each}}
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 > |
order.language |
general |
two-character ISO language code for the language in which the transaction was |
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 |
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 |
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 |
order.discountWithTax |
number |
amount of the discount applied to the order (if any) including any sales tax or VAT, |
order.discountWithTaxDisplay |
general |
amount of the discount applied to the order (if any) including any sales tax or VAT, |
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 |
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 |
order.tags |
general |
renders the values for any order-level custom tags that were associated with the {{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 |
order.address.addressLine2 |
general |
customer's address line 2 (if any) for orders with a physical product or required |
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 |
order.address.country |
general |
customer's country as specified in the address for orders with a physical product or |
order.address.postalCode |
general |
customer's postal code for orders with a physical product or required shipping |
order.items |
array |
array consisting of various fields of product information for the products that have usage example: {{#each order.items}} {{display}} {{/each}} |
product |
general |
product path for the current order item |
quantity |
number |
quantity of the current order item that was purchased |
display |
general |
display name for the current product |
subtotal |
number |
subtotal for the current order item |
sku |
general |
sku (if any) from the product record of the current order item |
attributes |
general |
custom attributes (if any) from the product record for the current order item |
discount |
number |
discount (if any) applied to the current order item, without currency indicator |
discountDisplay |
general |
discount (if any) applied to the current order item, formatted to include currency |
general |
subscription ID (if any) associated with the current order item | |
coupon |
general |
coupon code of any promotion applied to the current order item |
fulfillments |
array |
array consisting of various fulfillment-related fields (if any) applicable to the {{#each fulfillments}} {{#each this}} ((your fulfillment variables go here)) {{/each}} {{/each}}
|
type |
general |
type of the current fulfillment action, for the current product |
display |
general |
display name indicating the type of the current fulfillment action for the current |
license |
general |
license key (if any) issued for the current fulfillment action, for the current |
size |
number |
size of the download file associated with the current fulfillment action (if any), |
file |
general |
download URL for the file (if any) associated with the current fulfillment action, |
order.support.contactName |
general |
your support contact name, as configured under Settings > Store Settings > |
order.support.contactEmail |
general |
your support contact email address, as configured under Settings > Store Settings |
order.isRebill |
Boolean |
A Boolean value indicating whether or not the transaction was processed as an automatic |
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.
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
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).