Set up API-Based transactional events

❗️

This guide refers to Klaviyo's v1/v2 legacy APIs.

We are in the process of updating these guides, please check back later! For more information about the differences between legacy and new APIs, check out the comparison chart and [new API overview] (ref:api_overview).

In Klaviyo, there is no difference between transactional and non-transactional metrics and 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, see our Guide to using flows send transactional emails.

If you'd like to send transactional events to Klaviyo beyond the ones we track by default or those mentioned in other integration guides, use our server-side Track API.

📘

Info

Sending transactional events via the JavaScript Track API can be blocked by someone’s browser or device, so we don't recommend using this method. Instead, use the server-side Track API to send transactional events, since it’s 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
• Lead Tracking
  • Became Lead
  • New Lead

To send server-side events and profile properties, make a Track call to our server-side API. Generally speaking, these APIs require you to make an HTTP request (either GET OR POST) to the server. See our Track & Identify documentation for more information.

We also have the following SDKs available to assist you with server-side requests:

• Python
• Ruby
• PHP
• Node.js

The examples in this article review the types of payloads and the example scenarios in which you would want to track these events.

📘

Info

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.

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 understanding segment conditions.

If you have questions about customer integrations check out our Custom integration FAQ.

Server-side requests

You'll want to send server-side data to Klaviyo in one of two ways: real-time or batch.

• Real-time: requests are made as soon as an action is taken
• Batch: script runs at least once an hour, sending all events from the past hour to your Klaviyo account

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 (e.g., Order ID)
• If the same combination of event and $event_id are sent more than once, all subsequent tracked events with the same combination will be skipped
• 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 (e.g. first name) as profile properties in the customer_properties dictionary and any information specific to the event itself (e.g., 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

Trigger the Created Account event based on when someone initially signs up on your site. This event 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 the snippet below:

{
   "token": "PUBLIC_API_KEY",
   "event": "Created Account",
   "customer_properties": {
     "$email": "[email protected]",
     "$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

The Updated Account event is triggered whenever someone updates information in their account, such as their email address, name, or password. This event can then be used to send the emails confirming updated account information, next steps for account setup, or any other information related to their customer journey.

See the table below for the new properties to include in the properties dictionary:

See the code block below for an example of what the Updated Account payload should look like:

{
   "token": "PUBLIC_API_KEY",
   "event": "Updated Account",
   "customer_properties": {
     "$email": "[email protected]",
     "Birthday": "1989-01-18 00:00:00",
     "FavoriteColors": ["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
}

Updated email

Since Klaviyo uses email address as the primary identifier for a profile, you need to make an additional set of requests to update the email address or phone number (for SMS-only) in a person’s profile within your Klaviyo account. This takes advantage of the Klaviyo “person ID” for that person’s profile, which is the ultimate/uneditable identifier for a profile generated on our end.

📘

Info

These requests use your private API key, not your public API key. See our article on managing your API keys for more information.

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 protected]

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

The Reset Password event is triggered when a person requests to reset their password. When this happens, send the Reset Password payload with the URL of the reset password link included in the properties dictionary. This event can then be used to trigger a flow email for the person to reset their password using the reset password URL.

See the code block below for an example of what the Reset Password payload should look like:

{
   "token": "PUBLIC_API_KEY",
   "event": "Reset Password",
   "customer_properties": {
     "$email": "[email protected]"
   },
   "properties": {
     "$event_id": "1234",
     "PasswordResetLink": "https://www.website.com/reset/1234567890987654321"
   },
   "time": 1387302423
}

Order notifications

Use the following events to send order notifications to your customers.

Created invoice or created order

Use the Created Invoice and Created Order events when there’s an incomplete order which needs customer action (e.g., a signature, size selection, setting up billing frequency, etc.) before it can be processed on your end.

📘

Info

This event is similar to a Started Checkout event. Depending on your business and the data you send in the event payload, you may be able to track either just Started Checkout or Created Invoice. The main consideration is that an abandoned cart notification is not the same as an invoice notification.

• Abandoned cart notification: Encourages a person to complete a purchase they left behind
• Invoice notification: Notifies a customer they need to provide more information before their order can be completed

The type of notification you want to send will determine which event you can track.

Include the following in the properties dictionary:

• all of the invoice information entered by the customer
• any missing information (under MissingInformation, formatted as an array)

See the code block below for an example of what the Created Invoice payload should look like:

{
   "token": "PUBLIC_API_KEY",
   "event": "Created Invoice",
   "customer_properties": {
     "$email": "[email protected]",
     "$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

You can trigger an order confirmation off of a Placed Order event as long as the event contains all of the information required for an order confirmation email. The format of the order confirmation email will depend on your business, but typically, they include:

• Customer’s name
• Billing information
• Items purchased
• Payment method

See our other integration guides for examples of Placed Order events:

• Placed Order for a custom platform without a pre-built Klaviyo integration
• Placed Order for a subscription-based business (without a pre-built Klaviyo integration)

Failed payment

Use the Failed Payment event to notify a customer of a failed payment and, optionally, the steps they’ll need to take to complete the payment. This event has a similar structure to the Created Invoice event, and should include the following in the properties dictionary:

• The reason payment failed (string)
• Next steps to complete payment (string)
• All order information

See the code block below for an example of what the Failed Payment payload should look like:

{
   "token": "PUBLIC_API_KEY",
   "event": "Failed Payment",
   "customer_properties": {
     "$email": "[email protected]"
   },
   "properties": {
     "$event_id": "1234",
     "PaymentFailure": "Credit card not accepted",
     "PaymentNextSteps": "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

If you have access to the information, you can send shipping notifications to your customers. To create a trigger for shipping notifications, add an UpdateType to the properties dictionary, and track the following shipping statuses:

• Delivered
• Out for delivery
• Shipped

See the code block below for an example of what a shipping notification payload should look like:

{
   "token": "PUBLIC_API_KEY",
   "event": "Shipping Update",
   "customer_properties": {
     "$email": "[email protected]"
   },
   "properties": {
     "$event_id": "1234",
     "UpdateType": "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

Transactional emails are sometimes used for internal lead tracking purposes, which can occur on a prospective customer’s profile or a customer representative’s profile. In these instances, Klaviyo has the following lead tracking events:

Like other events, add customer information to the customer_properties dictionary and any lead-status-triggering actions (e.g., filling out a request form) to the properties dictionary.

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": "[email protected]",
     "$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": "[email protected]",
     "$first_name": "Jane",
     "$last_name": "Doe"
   },
   "properties": {
     "$event_id": "1234",
     "LeadFirstName": "John",
     "LeadLastName": "Smith",
     "LeadPhoneNumber": "5551234567",
     "LeadEmailAddress": "[email protected]",
     "LeadAction": "Filled out whitepaper request form"
   },
   "time": 1387302423
}

Additional resources

• API documentation
• Custom integration FAQ
• Guide to using flows to send transactional emails
• Understanding segment conditions