Date, Time, and Localization

Marketing emails frequently work with dates and tailor content to recipients’ regions. For example, when a new customer makes a purchase, you might send a discount code that expires in 10 days. You might also convert times to a customer’s time zone and convert currencies and number formats (like 12,000.00 vs 12 000,00) based on a customer’s region.

Depending on the flavor of Liquid you’re using, you’ll likely have a variety of filters that address most or all of these needs. We’ll give you an overview of common scenarios, and then you can explore your Liquid flavor’s documentation to learn what your options are.

The date filter

The date filter converts a timestamp value to a readable format. Timestamps are characters or encoded data that identify a date and time (like when your customer created an account or made a purchase), sometimes down to fractions of a second. 

Quick sidebar: timestamps are commonly stored in one of two formats. The first is a Unix timestamp, in which time is expressed as the milliseconds that have passed since January 1, 1970. This type of value is a number (specifically, an integer). The second format commonly used for timestamps is ISO 8601—also known as Universal Time Code (UTC) format. This type of value is a string. The UTC format is handy if you need to represent a date before 1970 (like if you want to represent a birth date for someone over 51!).

In either case, the output of a timestamp value is not at all human-friendly to read. That’s where the date filter comes in! Here’s a simple example using a orders.order_placed_at key, in which the value of that key is 1625079104—a Unix timestamp.

{{ orders.order_placed_at | date: "%D"}}

30/06/2021

The value of the orders.order_placed_at key is 1625079104, and we’ve applied the date filter to output a date that’s legible to a reader. 

The date filter is extremely flexible, offering a wealth of options for how your date will be displayed. You just need to include formatting instructions in the filter. In the example above, the instructions are “%D”, which displays the date in DD/MM/YYYY format—which happens to be a common format for dates in European countries.

But maybe you’re emailing someone in the US! Or maybe you want to include the day of the week, or even very specific details about the time—it’s all possible! You can see a full list of available date format instructions here (scroll down to the section titled “rfc822(date)” to see the list)—or make your life a lot easier by using this STRFTIME resource to generate the formatting instructions you want.

Let’s apply a date filter with more complex formatting instructions:

{{ orders.order_placed_at | date: "%A, %b. %d, %Y %I:%M %p %Z" }}

Monday, Jun. 30, 2021 11:51 AM Pacific Daylight Time

Woo, that’s a super detailed output—all we have to do is include the formatting instructions in the order we want things displayed, with the punctuation and spaces we want. That’s important: put the punctuation and spaces in the code; they will appear exactly as entered in your output.

See for yourself how the magic is done. Head over to the STRFTIME resource and see if you can generate the code and recreate the output above. 

Fun fact: if your timestamp is in ISO 8601 instead of Unix, you can convert it by using “date: %s” in the code of your filter; check out the “seconds since 1970” button at the STRFTIME resource to see it happen.

Practice problem 

Now it’s your turn to practice with the date filter. 

Format your timestamp like this: Monday, 21 June 2021. Feel free to use the STRFTIME resource to compose your instructions for the date filter.

Choose the right Liquid code from the options below:

{{ orders.order_placed_at | date: "%A, %e %B %Y"}}

{{ orders.order_placed_at | date: "%A %e %B %Y"}}

{{ orders.order_placed_at | date: "%a, %e %b %y"}}

{{ orders.order_placed_at | "%A, %e %B %Y"}}

That’s not right, try again!

{{ orders.order_placed_at | date: "%A, %e %B %Y" }}

Monday, 30 June 2021

Using the now key

Liquid has another handy tool for outputting dates: the now key (depending on the flavor of Liquid you’re using, it might also be called the today key). The value of the now key is always the current date and time. Used with the date filter, now will output the current time, like this: 

{{ 'now' | date: "%A, %b. %d, %Y %I:%M %p %Z" }}

Monday, June 30, 2021 11:51 AM Pacific Daylight Time

Keep in mind that, as with all Liquid code, the value of the now key will be the time at which the code is actually rendered—for an email, that means the time your platform creates the email, not the time your reader opens the email.   

Other date and time filters

Some Liquid flavors have filters that add or subtract time increments to a given timestamp, which can be helpful for dynamically calculating new dates. Let’s say someone signed up for an annual subscription, and you want to let them know the date it will expire. Here’s how you can do that using Customer.io’s add_year filter:

{{ orders.order_placed_at | add_year: 1 }}

Monday, June 30, 2022 11:51 AM Pacific Daylight Time

Note that this particular filter requires that your timestamp is a Unix timestamp; check out the documentation for your flavor of Liquid for any necessary details like that for the filters you’re using. 

Localization tools

Many Liquid flavors have tools that convert currency, number format, or other elements to match the customer’s region. Using a localization filter or adding a localization parameter (essentially, extra instructions) to a filter is one way to accomplish this. 

Let’s use Customer.io’s currency filter as an example. Heads up: for this example, we’re using the assign tag to create a new key and value (that’s the first line of code below) to make it easier to see how this currency filter works. You learned in Intermediate Keys that you can use the assign tag to create keys and store their values right in your Liquid code.

{% assign my_money = "123456.78 " %}
{{ my_money | currency }}

$123,456.78

The second line of code shows the currency filter. This filter defaults to US dollars, with a comma as the thousands separator and a period as the decimal separator. 

But what if you have a global audience? That’s where localization parameter comes in. Let’s use that same example, but this time add a parameter to the currency filter indicating that our recipient is in France. Take a look at the second line of code: 

{% assign my_money = "123456.78 " %}
{{  my_money | currency: "fr" }}

123 456,78€

Now the currency displayed is euros, with a space as the thousands separator and a comma as the decimal separator—the correct currency and number format for that region. Et voila! 

Take some time to look through your Liquid flavor’s documentation to learn how to manage dates, times, currency, and other localization options! It’s a great opportunity to make your emails more personalized and more engaging—and that means more clicks.

Up Next: Advanced Liquid – Whitespace Control