Using customer and order details in your automated email messages.

« Back to documentation.

Customizing your automated email messages with dynamic order data and customer data

Stages uses Handlebars for customizing the content in your automated emails. Handlebars gives you more control and flexibility, including support for iterating over a collection of items such as an order's line items or fulfillments.

Handlebars basics

A handlebars expression looks like {{some.content}} surrounded by a pair of double curly braces. All you have to do to use a handlebars expression is write it in your automation email template. When your automation rule is triggered, our server will find all handlebars expressions and replace them with the order's data.

For example, let's say you want to send a simple, automated email message to your team whenever an order's stage changes from 'Ready to Ship' to 'Shipped'. You would write something like this in your template:

Hello team,

Order #{{order.id}} has just switched from {{stage.from.name}} to {{stage.to.name}}. The customer's name is {{customer.first_name}} {{customer.last_name}}.

When that email is sent, it will be transformed into the following email message:

Hello team,

Order #12345 has just switched from Ready to Ship to Shipped. The customer's name is John Doe.

Of course, there are a lot more handlebars that you can use to customize your email messages, and you can see the full list of handlebars below. But first, let's talk about looping or iterating over an order's line items and fulfillments.

Injecting line items and fulfillments with handlebars

Handlebars is easy enough to use when you're referring to a single property such as an order ID or the customer's name, but looping over an order's collection of line items and fulfillments is slightly more involved.

To start a loop over a collection, you would write {{each order.lineitems}}. After starting a loop you can refer to the current item in the loop by prepending it with loop_var followed by the property you want to access, e.g. {{loop_var.productname}}.

(You can see the full list of line-item- and fulfillment-specific handlebars below.)

Finally, you must close the loop with {{end}}. If you don't close the loop, it won't work and your email message will break.

For example, let's say you want to send an email message to your team that contains a list of the line items in an order. Your template would look a something like this:

Hello team,

Order #{{order.id}} has the following line items:

{{each order.lineitems}}

* {{loop_var.productname}} purchased for ${{loop_var.price}}.

{{end}}

When sent, the email message will be transformed into the following:

Hello team,

Order #12345 has the following line items:

* Warsong T-shirt - Red purchased for $12.00.
* Darkspear Hoodie - Black purchased for $19.00.

For a more in-depth and technical look at everything you can do with Handlebars, please refer to the technical docs on substitutions by our email service provder, SparkPost.

All valid handlebars

The following is a list of all valid handlebars that can be used in your automated emails. Please note that handlebars are case-sensitive, and we will automatically convert them to lower-case when you create or update an automation rule.

Insert a link to the Stages order tracking widget that's embedded on your store:

  • {{stages.trackinglink}}.

Handlebars referring to the customer:

  • {{customer.firstname}}.
  • {{customer.lastname}}.
  • {{customer.email}} - The customer's email address.

Handlebars referring to the order:

  • {{order.id}}: The order's ID as it appears in your Shopify store.
  • {{order.created}}: The date and time the order was created, in a Jan 25, 2015 09:30 AM format.
  • {{order.CustomerNote}}: The note that the purchasing customer left on the order.
  • {{order.TeamNote}}: The note that you or your team have added to the order while using Stages.
  • {{order.payment.currency}}: The currency that the customer paid with.
  • {{order.payment.total}}: The total amount that the customer paid.
  • {{order.payment.totalusd}}: The total amount that the customer paid, in United States Dollars.
  • {{order.payment.tax}}: The total amount of tax that the customer paid.
  • {{order.payment.cardnumber}}: The customer's credit card number, masked in the •••• •••• •••• 1234 format.
  • {{order.payment.cardtype}}: The type of the customer's credit card, such as VISA or MasterCard.
  • {{order.lineitems}}: A collection of the order's line items, which must be looped over using the {{each order.lineitems}} handlebar and must be closed with the {{end}} handlebar. The following handlebars are available in the loop and refer to the current line item:
    • {{loop_var.price}}: The line item's price at the time of purchase.
    • {{loop_var.sku}}: The line item's SKU.
    • {{loop_var.producttitle}}: The line item's title. Ex: 'Warsong T-shirt'.
    • {{loop_var.productvarianttitle}}: The line item's variant title. Ex: 'Red'.
    • {{loop_var.productname}}: The line item's name, which is the title and variant title combined. Ex: 'Warsong T-shirt - Red'.
    • {{loop_var.productvendor}}: The line item's vendor.

Handlebars referring to the order's billing address:

  • {{billing.address.firstname}}.
  • {{billing.address.lastname}}.
  • {{billing.address.street1}}.
  • {{billing.address.street2}}.
  • {{billing.address.city}}.
  • {{billing.address.state}} - The full name of a state or province.
  • {{billing.address.postalcode}} - The ZIP or postal code.
  • {{billing.address.country}} - The full name of a country.
  • {{billing.address.countrycode}} - The abbreviated name of a country. Ex: USA.
  • {{billing.address.statecode}} - The abbrevated name of a state or province. Ex: IA or CA.

Handlebars referring to the order's shipping address:

  • {{shipping.address.firstname}}.
  • {{shipping.address.lastname}}.
  • {{shipping.address.street1}}.
  • {{shipping.address.street2}}.
  • {{shipping.address.city}}.
  • {{shipping.address.state}} - The full name of a state or province.
  • {{shipping.address.postalcode}} - The ZIP or postal code.
  • {{shipping.address.country}} - The full name of a country.
  • {{shipping.address.countrycode}} - The abbreviated name of a country. Ex: USA.
  • {{shipping.address.statecode}} - The abbrevated name of a state or province. Ex: IA or CA.

Handlebars referring to the order's fulfillments:

  • {{fulfillments}} - A collection of the order's fulfillments, which must be looped over using the {{each fulfillments}} handlebar and must be closed with the {{end}} handlebar. The following handlebars are available in the loop and refer to the current fulfillment:
    • {{loop_var.status}} - The fulfillment's current status.
    • {{loop_var.shippingcompany}} - The shipping company being used for this fulfillment, such as UPS or Amazon.
    • {{loop_var.trackingnumber}} - A tracking number to be used with the shipping company.
    • {{loop_var.trackingurl}} - A URl that the recipient can use to track this fulfillment.
    • {{loop_var.lineitems}} - The line items in the fulfillment, which must be looped over using the {{each loop_var.lineitems}} handlebar and must be closed with the {{end}} handlebar. The handlebars available in this loop are the same handlebars that are available in the above {{order.lineitems}} loop.

Handlebars referring to the order's previous and new stage in the Stages app:

  • {{stage.from.name}} - The name of the previous stage.
  • {{stage.from.color}} - The color of the previous stage. Ex: Red, Blue, Green, etc.
  • {{stage.to.name}} - The name of the new stage.
  • {{stage.to.color}} - The color of the new stage. Ex: Red, Blue, Green, etc.

Finally, you can use {{stages.trackinglink}} to send your customers a direct link to the Stages order tracking widget that's automatically embedded on your Shopify store. Your customers can use that link to easily track exactly where their order is in your manufacturing and fulfillment process.

Click here to head back to the docs.