Trigger behavior during a customer’s birthday month

Estimated time to implement: 45 minutes, difficulty: 5/10

When I give a company my birthday, I would expect them to somehow recognize it. This example will show you how to do just that!

Step one: add the JS Customer API to your theme

Make sure you’ve followed the instructions on how to install developer tools in order to include our lightweight API for your usage.

Step two: create a snippet to be used globally

We want to perform this logic wherever a customer can land on the storefront. The best way to do this is by adding code to your theme’s layout/theme.liquid file.

Create a snippet called handle-customer-birthday, then render it anywhere in the <body> element. It’s important to add your snippet within the <body> to ensure it gets evaluated after our app embed does.

<html>
  <head>
    ...
    {{ content_for_header }}
    ...
  </head>
  
  <body>
    {% comment %}
      Render your snippet here, within the <body> element:
    {% endcomment %}
    
    {% render 'handle-customer-birthday' %}
  </body>
</html>

Step three: Prepare JavaScript

In your handle-customer-birthday snippet, add the following code:

<script>
  CF.customerReady(function() {
    // Ready to handle customer data!
  });
</script>

The CF.customerReady function provides you with an easy way to ensure your code will only run when our code is ready.

Step four: Determine if it’s the customer’s birthday month

For the sake of this example, we’ll assume you have a data column with a key of birthday, and a data type of Date.

Use the CF.customer.get function to obtain the customer’s birthday:

<script>
  CF.customerReady(function() {
    // Ready to handle customer data!
    var birthday = CF.customer.get('birthday');

    console.log(birthday); // -> 1998-06-08
  });
</script>

Check to see if the data actually exists, since some customers may not have the birthday in their data:

<script>
  CF.customerReady(function() {
    // Ready to handle customer data!
    var birthday = CF.customer.get('birthday');
    if (!birthday) return;

    console.log(birthday); // -> 1998-06-08
  });
</script>

You’ll see that the data you get is a string, in the format of YYYY-MM-DD. Don’t create a Date with this data, or it will be a day behind.

CF.customer contains a method you can use to parse the value as a dayjs instance. This function needs to be called before you get any customer data.

<script>
  CF.customerReady(function() {
    // Convert birthday from a string to a dayjs instance
    CF.customer.parseDates('birthday');
    var birthday = CF.customer.get('birthday');
    if (!birthday) return;

    console.log(birthday); // -> c {$L: "en", $d: Mon Jun 08 1998 00:00:00 GMT-0700 (Pacific Daylight Time), $y: 1998, $M: 5, $D: 8, …}
  });
</script>

Now birthday is not a string. It’s a dayjs instance which contains many helpful tools we can use to analyze its value. Learn more about dayjs instances and what you can do with them.

Step five: check to see if the current month is the customer’s birthday month

Extract the month from `birthday`

Luckily for us, dayjs provides a very simple API we can use to get the month:

<script>
  CF.customerReady(function() {
    // Convert birthday from a string to a dayjs instance
    CF.customer.parseDates('birthday');
    var birthday = CF.customer.get('birthday');
    if (!birthday) return;

    var month = birthday.month(); // 0 = January, 1 = Feburary, ... 11 = December
  });
</script>

Get the current month

We expose dayjs in the CF namespace so you can use it. To initialize an instance, simply call it as a function:

var today = CF.dayjs();

You can get today’s month exactly how you did for birthday:

var today = CF.dayjs();
var thisMonth = today.month();

But we don’t really need both variables, so let’s condense it to a single statement:

var thisMonth = CF.dayjs().month();

Now add it to your script:

<script>
  CF.customerReady(function() {
    // Convert birthday from a string to a dayjs instance
    CF.customer.parseDates('birthday');
    var birthday = CF.customer.get('birthday');
    if (!birthday) return;

    var month = birthday.month(); // 0 = January, 1 = Feburary, ... 11 = December
    var thisMonth = CF.dayjs().month();
  });
</script>

Check for equality

The variables month and thisMonth are simple numbers. You can check for equality simply by using ==:

<script>
  CF.customerReady(function() {
    // Convert birthday from a string to a dayjs instance
    CF.customer.parseDates('birthday');
    var birthday = CF.customer.get('birthday');
    if (!birthday) return;

    var month = birthday.month(); // 0 = January, 1 = Feburary, ... 11 = December
    var thisMonth = CF.dayjs().month();

    if (month == thisMonth) {
      // It's the customer's birthday month!
    } else {
      // It's not :(
    }
  });
</script>

Next steps

How you want to handle the birthday is up to you. Inside the month == thisMonth condition, you may want to:

Redirect to a page offering a discount
Display a banner at the top of the page
Add a free gift to the cart using Cart.js

Remember, this will happen on every page loaded within the customer’s birthday month. If you only wish to invoke certain functionality once, make sure to set some sort of flag on the customer so you can determine whether or not any functionality should happen.