Getting Started with Klaviyo as a Developer: Mapping Data and Workflows to Klaviyo

Published in

Klaviyo Developer Blog

10 min readOct 31, 2022

This is the second article in our Getting Started as a Klaviyo Developer four-part series.

In the first part of the series, we discussed how to model data and workflows in Klaviyo (see article here). Now, we will dive into mapping these models to technical components, including websites, services, and Klaviyo. By doing this, we will create technical requirements to design end-to-end experiences. In the next article, we will discuss how to test techniques to be confident that the created experiences are working as designed.

Overview

Build requirements by mapping workflow and data models to technical components and Klaviyo objects/product features
Discuss tradeoffs between various technical considerations and how to identify them
Work through an example to build detailed requirements for an end-to-end experience

Mapping Data and Workflows

Data and Workflow diagram — Data and Workflow Diagram

When building data-driven experiences, the two main requirements (which we discussed in the last article) are: (1) the data, and (2) the workflows. The data required is usually straightforward, while the workflows are often abstract. For example, knowing you want to send a personalized email with the customer’s first name means you need the customer’s first name available when rendering the email template. The workflow where that email lives can be significantly more complex and may even create limitations on what data is available to you. Understanding what data you need, and the access patterns for that data are both essential to building data-driven experiences.

Below highlights important details to help ensure that you are not only making the data available, but also making it accessible when creating experiences.

Data availability and hygiene

When mapping data to technology components, it mostly comes down to two factors:

Determining the required data
Having proper access to that data

Having proper access means that the data can be delivered timely, securely, and accurately. This may require ETL type processes and other data hygiene to get the data into the correct format. Fortunately, most modern systems abstract granular data management, so unless you are building a backend system from scratch, you probably don’t need to worry about encoding or serialization of the data. However, depending on where in the stack your solution lives, you may need to make some of those granular considerations.

For higher level modern systems, you will likely be passing around JSON data. For legacy systems, you may end up ingesting csv files, which are often in UTF-8, but could be in other formats as well. Knowing and being able to predict the format of the data is an essential part of the system.

Mapping workflows into technology components and Klaviyo objects

In the last article, we discussed creating workflows. Mapping those workflows to technology components comes down to several factors. What technology you should use is also a major consideration. Here are some general tips to keep in mind, when picking technical components for your system:

Try to use what you have: Today, many tools offer if-this-then-that type functionality that you can utilize to accomplish simple ETL type tasks. This may be sufficient to create many of the experiences you want to create. Klaviyo offers a webhook action within our Flows product, which can be used to send HTTP POST requests for several incoming events. We published an article about using ‘Google sheets as a dynamic data source’. There are probably a lot of possibilities to be creative within your current tools, see how far you can stretch them before you reach for something additional.
Stateless: When you do need a new piece of technology, not needing to manage complex stateful infrastructure is a huge benefit. Prefer simpler technologies such as AWS Lambda and other infrastructure-as-a-service providers before rolling your own. This is especially true in the prototyping phase.
Stateful service: When the service you need has very complex requirements, it can eventually be required to build a standalone service to support it. One major benefit to the above guidelines is that the platform you are using will mostly handle maintenance for you. When you decide to roll your own system, you will now be responsible for maintenance. This might mean scheduling an hour a week where you will login and update things such as the operating system and other dependencies. This is a critical requirement and needs to be part of your planning when building. It is important to have a well maintained system that won’t randomly cause unnecessary fixing.

Tip: Logging and monitoring: Seeing activity in the form of graphs or other checks is a critical part of managing technical components.

Setting up alerting thresholds to identify when errors are occurring or data is no longer flowing will set you up for a successful project where you can catch issues early. Eventually APIs will change and things that you rely on will have outages, preparing for this is essential.

Use-case: Building a back-in-stock alerting experience

We’re going to work through a sophisticated experience that requires the use of Klaviyo in conjunction with technical components. Today, Klaviyo offers Back-in-Stock as native functionality for all catalog integrations (including those powered by our new Catalogs API), but this was not always the case. The example here is based on a system that a customer utilized before this functionality was available. This type of design is applicable to a wide variety of use cases, and can be generalized to an event-driven system working to send events to Klaviyo.

Many event-driven experiences that are based on change-of-state can follow the same patterns outlined here to accomplish the desired experience for end users.

Use-Case: Description

When a user arrives on our website and a product is out-of-stock, we want to allow them to sign up to be alerted when the product becomes available. Additionally, as part of this system, when the product is restocked, we want to send an automated email/sms notification to be sent to the user alerting them that the product is available again.

Modeling the data and Klaviyo object mappings

For our back-in-stock example, building upon the last article where we designed Data and Workflows(see here if you would like to refer back), and extending this modeling to include data and workflow mapping.Now let’s create the data that we need to make this experience happen.

Modeling the data

Data objects: Customer, Product

Customer {
  First Name: David
  Last Name:
  Email:
  Phone-Number:
}Product {
  Name:
  Description:
  Image:
  Inventory:
  Back-in-stock-list: []
}

Now to extend this to Klaviyo, we are going to map those data objects to native Klaviyo objects.

Klaviyo object mappings:

Customer → Profile
Product → Catalog Item (Product)

To build the back-in-stock experience, we need customer data, this includes properties such as their name and contact information. We also need product data, including inventory, product description information to put into a message form, and the list of users waiting for the product to be back in stock.

Modeling the workflow

For this workflow, we are going to need to track certain data and events, including when the product inventory changes for a back-in-stock item. Specifically:

When a product is out of stock, we need a way for customers to sign up.
When the product comes back in stock, we need to notify the customers.

Mapping the workflow to technical components and Klaviyo objects

There are a lot of options in how you could map this workflow to technical components. Let’s consider some of the requirements and ways to achieve them, utilizing the ideas above about how to prioritize different potential solutions.

Requirement: Store the customer information
— Solution: Klaviyo Profile
Requirement: Store the product information
— Solution: Klaviyo Catalog Item (Product)
Requirement: Store the back-in-stock waiting list
— Solution: ?
Requirement: Create events for back-in-stock items
— Solution: Klaviyo Event

For the first two we can store the customer information and product information using native Klaviyo objects. We can use Klaviyo’s APIs to send and store this data. However, for the back-in-stock waiting list and the system to generate events when the product is back in stock, we don’t have a clear solution. Let’s consider possibilities:

Try to use what we have — as we discussed above, we don’t have this option with Klaviyo alone, so we need to look at other options.
Stateless: For accepting incoming data from the website for signed up users, and storing it, we could use a stateless setup such as AWS Lambda + S3 or equivalent technologies. The processing of the incoming data is handled by Lambda, and the data is passed to storage in S3. Then, every so often a request from Lambda can sync the product catalog to check for inventory changes.
Stateful service: Instead of using stateless components to create this experience, we could create a service that handles the processing and storage. The overall strategy will be very similar, but the technological components will be lower level.

To make this use-case happen, we can choose a stateless or stateful solution. Depending on the current infrastructure that you utilize, it is up to you to decide what would work best. If you already have a server that handles cron tasks and is connected to a database, it might be simple to also support this use-case. If you do not have any infrastructure, and are interested in keeping it that way, you may prefer a stateless approach.

Translating requirements into technology components and integrating with Klaviyo leaves tons of room for creativity. The ideas here are intended to be guidelines, but as long as your technological solution can solve the requirements and is maintainable, you can use all types of different strategies. This is where the art exists in software development.

Technical components: explained and diagramed

Below describes a system that solves our requirements. The main differences between stateless and stateful architectures would be the components. For processing in a stateless system, we could use Lambda and S3, and in a stateful system we could use EC2 and a database.

System design for Back-in-Stock — System Design for Back-in-Stock

Website: Back-in-stock form

When the product is out of stock, we need to display a form to the user to allow them to sign up for the back-in-stock list. We’ll assume the platform where the product displayed in this example is a website, but it could also be an app, or another platform.

Processing Layer: Form and catalog data

In this case, we need a system that can accept incoming data and then add the customer to a list specific to that product. When a product is restocked, we want to iterate through the list of users waiting for the alert, and create an Event in Klaviyo for each one.

One way to implement this is to run a task at 15 or 30 minute intervals. This task compares the current product inventory in storage to the current product stock. Then, when a product that previously had zero inventory or a flag to distinguish it was out of stock either has stock added or the flag swaps, this represents a back-in-stock event. At this point, each user on the waiting list receives a Klaviyo Event:

{ "data": {
    "type": "event",
    "attributes": {
      "profile": {
        "email": "david.henriquez@klaviyo.com"
        },
      "metric": {
        "name": "Back In Stock Alert"
      },
      "properties": {
        "ProductName": "New Value",
        "ProductDescription": "New Value"
      }
    }
  }
}

Storage layer: Catalog data and back-in-stock list

Once we have processed the incoming form and catalog data, we need to store it somewhere. This requires us to store the list of users for each product, and the product information including inventory.

Error States: When designing a system, it is important to consider what can go wrong and how to handle errors. In our next article, we will discuss testing strategies and how to plan for and handle errors that may occur.

For simplicity, we could store all of this data together. The product could have an array/list of users that are waiting for it to be back in stock. We could also store this information separately, and use a JOIN or equivalent operation to combine the product data with the back-in-stock waiting list for that product. How you store the data is up to you.

Example product storage schema:

productName: String,
productDescription: String,
productSKU: String,
productImageURL: String,
productPrice: Number,
productPageLink: String,
productAlternateImageURL: String
bisWaitingList: { type: Array, "default" : []},

Summary

In this article, we discussed how to map data and workflow models to Klaviyo and other technical components. We considered tradeoffs between using existing technologies, using stateless components, and creating a stateful service. We also discussed ideas around an event-driven experience. In this case, we used a Back-in-Stock system as the example, but many other event-driven experiences would behave similarly and could use a very similar approach.

What’s next?

In the next article, we are going to discuss testing strategies to ensure we can be confident end-to-end that our solution is working. This will include how to create and utilize example data in both Klaviyo and other technical components that make up the system.

In the meantime, to learn more about Klaviyo’s new APIs, check out the new documentation here to get started!