---

Welcome to Klaviyo’s Developer Showcase!

Hello! As a brief intro, my name is Justin Fink and I lead developer marketing at Klaviyo. We are starting a developer showcase series where we’ll be interviewing developers that have built on top of Klaviyo. They will share tips-and-tricks for utilizing Klaviyo’s APIs, SDKs, and more to help our developer community thrive.

If you’re interested in sharing your story, please reach out to developers@klaviyo.com and we’d love to connect!

For our first discussion, I’ll hand it off to Brian Whalley to tell his story!

Background:

I’m Brian Whalley, one of the founders of Wonderment, an order tracking and management app that recently raised $6M in seed funding. Our goal in the future is to improve the experience around shipping for both merchants and consumers.

So why did I build on top of Klaviyo?

As I was starting an eCommerce business focused on providing merchants with strong support for transactional messaging and shipping notifications, we wanted to utilize a best-in-class platform for sending out communications via SMS / email, which was why the Klaviyo integration was the first we built to communicate with teams and customers.

• Nearly all of our hundreds of customers utilize Klaviyo, and we use Klaviyo’s APIs for millions of events per month, so our customers can use the best-of-breed platform they already utilize for messaging.

Why should you read this?

I want to share some tips for building a great Klaviyo integration with other app developers out there and I hope this will help more of you get started on the right path.

Klaviyo Insights: Track API

Klaviyo’s Track API is incredibly versatile in terms of how it can accept event data and is an important, high-leverage integration point because of how that data can be used downstream — e.g. for analytics, segmentation, triggering automations, and personalizing content.

Typically, apps have some unique data, like behavior or interaction data, that you want to use to trigger flows or segment audiences inside of Klaviyo. A good example of this is shipping data, like we have — where we integrate with all of the carriers a store uses, and we help get that data into the right place, in the right format. This could also be based on meta-events though. For example, Reviews apps often want to wait for a package to be delivered, and then send a Track API event like “Eligible for Review”, which kicks off a flow in Klaviyo, so that the review request email goes out only after a delivery has happened.

Tips, Tricks, and Learnings: Track API

1. The payload for a request to the Track API can contain any JSON.

Upsides of this include:
“Since Klaviyo doesn’t impose a rigid data schema, it’s easy to send in just about any arbitrary data without having to do annoying manipulations or data mappings and without having to pre-configure a data schema in the app.
Any of this JSON can be dynamically rendered into emails if you build a flow triggered on this event, which makes personalization a lot easier and more flexible than in some other systems.”

Tradeoffs Include:
“Klaviyo’s flow logic, like flow splits or filters, can only see one layer deep in the JSON data structure, meaning that you may need to think about ‘top-leveling’ certain properties within the JSON.”

Example:
Stores often want to branch email order confirmation or delivery emails based on the products in the order. This allows them to easily add product-specific messaging to the email. While we nest complete data about each line item in the order in the event, we also raise the product names and SKUs to the top level of the event, so that they can easily make a split or filter.
You can also see an example of this on any ‘Placed Order’ event in Klaviyo, where each item is stored in an Items list. This makes it easy for customers to branch flow.”

2. Klaviyo’s events are immutable.

What does this mean? After you send event data to Klaviyo, it can’t be changed (by design). Because of this, you should be thoughtful about keeping event names and structures as stable as possible.

This hassle can be easily avoided if you’re thoughtful about naming conventions up front. Some recommendations:

Name your events with your company or app name as a prefix (so they show up next to each other in the UI). Follow a standard pattern in terms of casing and whitespace (e.g. our event names look like this “Wonderment – Attempted Delivery”).
You can also assign an icon to your event as well though unfortunately the icons are not available to 3P party developers at this time as they’re reserved for Klaviyo-built integrations.
Therefore, naming your events well is the next best thing you can do for now.”

Example:
“Let’s say you alter the way you name an event (e.g. you start sending in the same event but by a different name or capitalization), this will create a new event in Klaviyo.
If you have a flow triggered on the original event, you’d need to clone the original flow and change the trigger to the new event. And since the original event has been replaced, you’d similarly need to replace it in any flow or segmentation logic.”

3. Include as much metadata as you can.

The segmentation and filtering capabilities of Klaviyo are insanely powerful, so it’s in your best interest to include as much relevant information as possible that your customers can segment on. The more data you enable, the more powerful flows your customers will create, and the stickier your app will be.

4. Trigger seed events for your key events, with a sample value in each metadata field.

That way they can begin flow development immediately, and all of the metadata values will be populated in the flow or segment builder.

5. Get and Post Requests

Klaviyo’s Track API originally accepted GET requests with the JSON payload sent as a base64-encoded data parameter on the request. If you use this endpoint, you need to make sure you URL-encode the payload after base64-encoding, otherwise you could have URL-unsafe characters such as `+` or `=` which could cause the request to be accepted by the API (return an HTTP 200), but not successfully processed (return a `0` in the body of the response).

The GET /track endpoint has a fairly low size limit on the request. The POST endpoint has a 1 MB limit, which should be enough for even very large event data payloads. However, keep in mind your defined timeout length on your requests when sending very large payloads into Klaviyo. If you’re sending data >100 KB on a regular basis, you may hit timeouts that cause your events to not register.

That’s a Wrap!

If you’re interested in learning more about Klaviyo’s APIs and developer experience, please visit Klaviyo’s developer portal, developers.klaviyo.com and if you want to write about your experience as a Klaviyo Developer, reach out to developers@klaviyo.com!