Setting Up API-based Transactional Events

read
Last updated at:

Overview

In Klaviyo, there is no difference between transactional and non-transactional metrics in relation to the types of messaging they result in. You can trigger marketing content and transactional content off of the same metrics; the only difference is that we define a transactional email as an essential, non-marketing email. Transactional emails are typically sent in response to a direct interaction with your brand in which it is imperative that the customer receives a response. For more information on the difference between transactional and marketing emails, check out this guide

If you'd like to send transactional events to Klaviyo (beyond the ones we track by default or those mentioned in other integration guides), you can send them using our server side Track API. While you can send transactional events via Javascript Track API, we don't recommend this method because events may be blocked by an individual's browser or device. Rather we recommend sending transactional events via server side Track API which is a safer, more reliable method of transmission. 

This guide will provide examples of how to implement the following common transactional events:

  • Account Notifications
    • Created Account
    • Updated Account
    • Updated Email
    • Reset Password
  • Order notifications
    • Invoice Created
    • Order Confirmation
    • Failed Payment
  • Shipping notifications
    • Shipping Confirmation
    • Shipping Update
    • Shipment Out for Delivery
    • Shipment Delivered
  • Lead Tracking
    • Became Lead
    • New Lead

We have libraries available for Python, Ruby, and PHP, but in a general sense the API just requires making an HTTP GET request with a base64 encoded JSON payload. The examples below review the types of payload and the example scenarios in which you would want to track these events.

The level of detailed data you send to Klaviyo within these website, purchase, and shipment events will determine how you can filter and segment based on these events in Klaviyo. To understand how data must be structured so that key event details are available for segmentation, check out our guide on segment conditions.

Note that the snippets in this guide use example data. You will need to update the values of the JSON properties in these snippets such that they dynamically pull from the relevant information needed for that property.

If you have questions about customer integrations check out our custom integration FAQ or reach out to our Support Team for help.

Server-side requests

For transactional events, you should make a Track request to our server-side API. You'll want to send server-side data to Klaviyo in one of two ways: real-time or batch.

  • Real-time - You'll make requests as soon as an action is taken
  • Batch - You’ll write a script that will run at least once an hour to send all events that occurred in that past hour

Key things to be aware of when tracking server-side events:

  • Make sure to replace PUBLIC_API_KEY with your public API key.
  • The $event_id should be a unique identifier for the order (eg. Order ID).
  • If the same combination of event and $event_id are sent more than once, we will skip all tracked events after the first with the same combination.
  • time is a special property that should be a UNIX timestamp of the order date and time.

Server-side events should include any information about the person who took the action (eg. first name) as profile properties in the customer_properties dictionary and any information specific to the event itself (eg. a list of ordered items) in the properties dictionary.

Account Notifications

If people are able to create accounts on your website and you want to send them messaging around this, it will be important to track the events specific to the messaging you want to send.

Created Account

A good place to start is a Created Account event when someone initially signs up. This can be used to send account creation confirmations and welcome emails, thanking the new subscriber or reviewing what they’re able to do now that they’ve made an account. The payload should look something like this:

{
   "token": "PUBLIC_API_KEY",
   "event": "Created Account",
   "customer_properties": {
     "$email": "john.smith@test.com",
     "$first_name": "John",
     "$last_name": "Smith",
     "$phone_number": "5551234567",
     "$address1": "123 Abc st",
     "$address2": "Suite 1",
     "$city": "Boston",
     "$zip": "02110",
     "$region": "MA",
     "$country": "USA",
     "FavoriteColors": ["green","yellow"]
   },
   "properties": {
     "$event_id": "1234"
   },
   "time": 1387302423
}

Updated Account

Any time someone updates their account information (eg. their email, name, password, etc), send an Updated Account event. This can be used to send confirmation emails about what was updated or emails about next steps for their account setup or customer journey. For this event, also include a property for the type of update (Update Type below) that occurred (eg. updating preferences, updating email address, updating password) and any data you would like to include as part of the followup email or filtering to be performed on this event. The payload should look something like this:

{
   "token": "PUBLIC_API_KEY",
   "event": "Updated Account",
   "customer_properties": {
     "$email": "john.smith@test.com",
     "Birthday": "1989-01-18 00:00:00",
     "Favorite colors": ["green","yellow","black"]
   },
   "properties": {
     "$event_id": "1234",
     "UpdateType": "Property Update",
     "UpdatedProperties": ["Favorite colors","Birthday"],
     "OldValues":{
       "Birthday": "",
       "FavoriteColors": ["green","yellow"]
     },
     "NewValues":{
       "Birthday": "1989-01-18 00:00:00",
       "FavoriteColors": ["green","yellow","black"]
     }
   },
   "time": 1387302423
}

Email updates

Because Klaviyo uses email address as the primary identifier for a profile, an additional set of requests needs to be made in order to update the email address on the person’s profile in your Klaviyo account. This will take advantage of the Klaviyo “person ID” for that person’s profile which is the ultimate/uneditable identifier for a profile generated on our end. Note that these requests use your private API key and not your public API key.

  1. First, make the following GET request using the person’s old email address to retrieve their Klaviyo person ID:
    https://a.klaviyo.com/api/v2/people/search?api_key=PRIVATE_API_KEY&email=john.smith@test.com
  2. Next, use the following PUT request, replacing PERSON_ID with the person ID retrieved from the previous request:
    https://a.klaviyo.com/api/v1/person/PERSON_ID?api_key=PRIVATE_API_KEY&email=NEW_EMAIL_ADDRESS

Reset Password

If a person requests to reset their password and they are required to click a link in a followup email, send a Reset Password event with that link as part of the payload. This can then be used to trigger a flow email containing that link for person to reset their password. The payload should look something like this:

{
   "token": "PUBLIC_API_KEY",
   "event": "Reset Password",
   "customer_properties": {
     "$email": "john.smith@test.com"
   },
   "properties": {
     "$event_id": "1234",
     "PasswordResetLink": "https://www.website.com/reset/1234567890987654321"
   },
   "time": 1387302423
}

Order Notifications

Created Invoice

Sometimes customers can create orders over the phone, in-store, or in some other way that creates an order in a not-yet-completed state. In cases like these, it may be helpful to send a Created Invoice or Created Order event in order to notify the customer that there are still actions to take (signature, size selection, billing frequency) before you are able to process their order.

Note, this event is similar in concept to a Started Checkout event and depending on your business and the data you send in the event payload, you may be able to use these events interchangeably (ie. only track either Started Checkout or Created Invoice). The important aspect here is that an abandoned cart notification is not the same as an invoice notification. In one case, the abandoned cart notification encourages a person to complete a purchase they left behind. In another case, a customer may have thought they completed a purchase, but they need to be notified that some information is missing which is needed to finalize the order.

The payload should include any information the person entered as part of the invoice and also any information still needed to complete the purchase and finalize the order. It should look something like this:

{
   "token": "PUBLIC_API_KEY",
   "event": "Created Invoice",
   "customer_properties": {
     "$email": "john.smith@test.com",
     "$first_name": "John",
     "$last_name": "Smith",
     "$phone_number": "5551234567",
     "$address1": "123 Abc st",
     "$address2": "Suite 1",
     "$city": "Boston",
     "$zip": "02110",
     "$region": "MA",
     "$country": "USA"
   },
   "properties": {
     "$event_id": "1234",
     "MissingInformation": ["Shipping Address Information","Shipping Method"],
     "$value": 29.98,
     "Categories": ["Fiction", "Classics", "Children"],
     "ItemNames": ["Winnie the Pooh", "A Tale of Two Cities"],
     "Brands": ["Kids Books", "Harcourt Classics"],
     "DiscountCode": "Free Shipping",
     "DiscountValue": 5,
     "Items": [{
         "ProductID": "1111",
         "SKU": "WINNIEPOOH",
         "ProductName": "Winnie the Pooh",
         "Quantity": 1,
         "ItemPrice": 9.99,
         "RowTotal": 9.99,
         "ProductURL": "http://www.example.com/path/to/product",
         "ImageURL": "http://www.example.com/path/to/product/image.png",
         "Categories": ["Fiction", "Children"],
         "Brand": "Kids Books"
       },
       {
         "ProductID": "1112",
         "SKU": "TALEOFTWO",
         "ProductName": "A Tale of Two Cities",
         "Quantity": 1,
         "ItemPrice": 19.99,
         "RowTotal": 19.99,
         "ProductURL": "http://www.example.com/path/to/product2",
         "ImageURL": "http://www.example.com/path/to/product/image2.png",
         "Categories": ["Fiction", "Classics"],
         "Brand": "Harcourt Classics"
       }
     ],
     "BillingAddress": {
       "FirstName": "John",
       "LastName": "Smith",
       "Company": "",
       "Address1": "123 abc street",
       "Address2": "apt 1",
       "City": "Boston",
       "Region": "Massachusetts",
       "Region_code": "MA",
       "Country": "United States",
       "CountryCode": "US",
       "Zip": "02110",
       "Phone": "5551234567"
     },
     "ShippingAddress": {
       "FirstName": "",
       "LastName": "",
       "Company": "",
       "Address1": "",
       "Address2": "",
       "City": "",
       "Region": "",
       "RegionCode": "",
       "Country": "",
       "CountryCode": "",
       "Zip": "",
       "Phone": ""
     }
   },
   "time": 1387302423
}

Order Confirmations

Order confirmations can be triggered off of a Placed Order event as long as that event contains all of the information required for these emails. This tends to differ based on the type of business, but more often than not you’ll want to include the person’s name, billing information, items purchased, and payment method. For examples on what a Placed Order event looks like, please see our other integration guides:

Failed Payment

Similar to the messaging around a Created Invoice event, if a payment fails you will need to communicate this to the customer and let them know that an action must be taken in order to complete the purchase. To enable this, send a Failed Payment event with information about what part or what type of payment failed. You can also send information about the order in questions so the notification is more readily identifiable to the customer. The payload may look like the following:

{
   "token": "PUBLIC_API_KEY",
   "event": "Failed Payment",
   "customer_properties": {
     "$email": "john.smith@test.com"
   },
   "properties": {
     "$event_id": "1234",
     "Payment failure": "Credit card not accepted",
     "Payment next steps": "Please use a different payment method or contact your credit card provider",
     "$value": 29.98,
     "Categories": ["Fiction", "Classics", "Children"],
     "ItemNames": ["Winnie the Pooh", "A Tale of Two Cities"],
     "Brands": ["Kids Books", "Harcourt Classics"],
     "Items": [{
         "ProductID": "1111",
         "SKU": "WINNIEPOOH",
         "ProductName": "Winnie the Pooh",
         "Quantity": 1,
         "ItemPrice": 9.99,
         "RowTotal": 9.99,
         "ProductURL": "http://www.example.com/path/to/product",
         "ImageURL": "http://www.example.com/path/to/product/image.png",
       },
       {
         "ProductID": "1112",
         "SKU": "TALEOFTWO",
         "ProductName": "A Tale of Two Cities",
         "Quantity": 1,
         "ItemPrice": 19.99,
         "RowTotal": 19.99,
         "ProductURL": "http://www.example.com/path/to/product2",
         "ImageURL": "http://www.example.com/path/to/product/image2.png",
       }
     ]
   },
   "time": 1387302423
}

Shipping Notifications

In order to let a customer know where their order is and when they’ll receive it, you may want to send shipment notifications. The important aspects of this event are the information about the shipment and the type of update to the shipment that occurred. For example, you may want to include the “update types” in order to deliver messaging to the customer about the state of their shipment in each of these cases:

  • Shipped
  • Out for delivery
  • Delivered
{
   "token": "PUBLIC_API_KEY",
   "event": "Shipping Update",
   "customer_properties": {
     "$email": "john.smith@test.com"
   },
   "properties": {
     "$event_id": "1234",
     "Update type": "Out for delivery",
     "Items": [{
         "ProductID": "1111",
         "SKU": "WINNIEPOOH",
         "ProductName": "Winnie the Pooh",
         "Quantity": 1,
         "ProductURL": "http://www.example.com/path/to/product",
         "ImageURL": "http://www.example.com/path/to/product/image.png"
       },
       {
         "ProductID": "1112",
         "SKU": "TALEOFTWO",
         "ProductName": "A Tale of Two Cities",
         "Quantity": 1,
         "ProductURL": "http://www.example.com/path/to/product2",
         "ImageURL": "http://www.example.com/path/to/product/image2.png"
       }
     ],
     "ShippingAddress": {
       "FirstName": "John",
       "LastName": "Smith",
       "Company": "",
       "Address1": "123 abc street",
       "Address2": "apt 1",
       "City": "Boston",
       "Region": "Massachusetts",
       "Region_code": "MA",
       "Country": "United States",
       "CountryCode": "US",
       "Zip": "02110",
       "Phone": "5551234567"
     },
   },
   "time": 1387302423
}

Lead Tracking

Sometimes transactional emails are used for internal purposes. If you want to let a representative at your business know when a person becomes a lead or takes a specific type of action that would qualify them for a more personal reach-out for example, track a Became Lead-style event.

Like other events, this event should contain information that the person entered about themselves in the customer_properties dictionary and any information specific to the lead-status-triggering action they took (eg. filling out a request form) in the properties dictionary. The difference between this and other events is that you may want to track it in both the profile of the prospective customer (for reporting purposes) and also in the profile of the representative who will take ownership of the lead (to let them know there’s a new lead). In order to do this, you’ll need to send two events with slightly different payloads; we’ll call these Became Lead (for the prospective customer’s profile) and New Lead (for the representative’s profile). The payloads should look like this:

Became Lead

Use this action to filter and report on new lead activity as a whole or send confirmation emails surrounding the action the lead took.

{
   "token": "PUBLIC_API_KEY",
   "event": "Became Lead",
   "customer_properties": {
     "$email": "john.smith@test.com",
     "$first_name": "John",
     "$last_name": "Smith",
     "$phone_number": "5551234567",
     "$address1": "123 Abc st",
     "$address2": "Suite 1",
     "$city": "Boston",
     "$zip": "02110",
     "$region": "MA",
     "$country": "USA",
     "MostRecentLeadSource": "Whitepaper request form"
   },
   "properties": {
     "$event_id": "1234",
     "Action": "Filled out whitepaper request form"
   },
   "time": 1387302423
}

New Lead

Use this event to trigger a transactional email to your representative so they can take further action on the new lead.

{
   "token": "PUBLIC_API_KEY",
   "event": "Became Lead",
   "customer_properties": {
     "$email": "jane.doe@sales.com",
     "$first_name": "Jane",
     "$last_name": "Doe"
   },
   "properties": {
     "$event_id": "1234",
     "LeadFirstName": "John",
     "LeadLastName": "Smith",
     "LeadPhoneNumber": "5551234567",
     "LeadEmailAddress": "john.smith@test.com",
     "LeadAction": "Filled out whitepaper request form"
   },
   "time": 1387302423
}
x
Was this article helpful?
11 out of 24 found this helpful