Developer showcase is a series where we interview developers that have built on top of Klaviyo. They 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, reach out to developers@klaviyo.com. If you’re interested in learning more about Klaviyo’s APIs and developer experience, visit developers.klaviyo.com.
What’s your 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.
Why did you 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 and 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 use 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 people 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’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.
Can you share any tips, tricks, and learnings?
1. The payload for a request to the track API can contain any JSON
Upsides of this: 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 of this: 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
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.
Avoid the hassle by being thoughtful about naming conventions up front. Tips:
- 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, though unfortunately the icons are not available to third-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.
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 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. Understanding 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.
