Set up API-Based transactional events

In Klaviyo, 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, read How to use flows to send transactional emails.

If you'd like to send transactional events to Klaviyo beyond those laid out here or mentioned in other integration guides, use our server-side Create Event endpoint.

📘
Sending transactional events via a Client endpoint can be blocked by someone’s browser or device, so we don't recommend using this method. Instead, use the server-side Create Event endpoint 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 Create Event call to our server-side endpoint. Generally speaking, these APIs require you to make an HTTP request (either GET OR POST) to the server.

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

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

📘
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 custom integrations, check out our Custom integration FAQs.

Server-side requests

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

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 sending server-side events to Klaviyo:

The unique_id should be a unique identifier for the event (e.g., Order ID).
If the same combination of metric name and unique_id are sent more than once, all subsequent events with the same combination will be skipped.
time is a special property. You can review our guide to acceptable date and timestamp formats to learn more.

Server-side events should include any information about the person who took the action (e.g. first name) as profile properties in the profile 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 is important to track 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 confirmation 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:

{
    "data": {
         "type": "event",
         "attributes": {
              "profile": {
                   "$email": "[email protected]",
                   "$first_name": "John",
                   "$last_name": "Smith",
                   "$phone_number": "+15551234567",
                   "$address1": "123 Abc st",
                   "$city": "Boston",
                   "$zip": "02110",
                   "$region": "MA",
                   "FavoriteColors": ["green","yellow"]
              },
              "metric": {
                   "name": "Created Account"
              },
              "properties": {
              },
              "time": "2022-01-01T00:00:00",
              "unique_id": "1234"
         }
    }
}

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 emails confirming updated account information, next steps for account setup, or any other information related to the customer journey.

See the table below for the new properties you could include in the properties dictionary:

Property	Type	Description
`UpdateType`	string	Description of the properties being updated
`UpdatedProperties`	array	Properties being updated
`OldValues`	dictionary	Current values of the properties in Klaviyo
`NewValues`	dictionary	New values for the properties

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

{
    "data": {
         "type": "event",
         "attributes": {
              "profile": {
                   "$email": "[email protected]",
                   "$first_name": "John",
                   "$last_name": "Smith",
                   "$phone_number": "+15551234567",
                   "$address1": "123 Abc st",
                   "$city": "Boston",
                   "$zip": "02110",
                   "$region": "MA",
                   "FavoriteColors": ["green","yellow","black"],
                   "Birthday": "1989-01-18 00:00:00"
              },
              "metric": {
                   "name": "Updated Account"
              },
              "properties": {
                  "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": "2023-01-10T00:00:00",
              "unique_id": "1234"
         }
    }
}

Updated email

Since Klaviyo uses email address as the primary identifier for a profile, you will need to make an additional set of requests if you want to update the email address of profile within your Klaviyo account. The same process applies if you want to update the phone number for an SMS-only profile. When a profile is created in your Klaviyo account, Klaviyo will assign an uneditable 26-character identifier to the profile. This identifier, also known as the Profile ID, is present in the URL of the profile in the dashboard.

You can update a profile by making a request to our Update Profile endpoint using the Profile ID. You can also refer to our article on updating profile identifiers via API for more information.

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 below for an example of what the Reset Password payload should look like:

{
    "data": {
         "type": "event",
         "attributes": {
              "profile": {
                   "$email": "[email protected]"
              },
              "metric": {
                   "name": "Reset Password"
              },
              "properties": {
                  "PasswordResetLink": "https://www.website.com/reset/1234567890987654321"
              },
              "time": "2023-01-10T00:00:00",
              "unique_id": "1234"
         }
    }
}

Order notifications

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

Created Invoice or Created Order notifications

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.

📘
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 below for an example of what the Created Invoice payload should look like:

{
    "data": {
         "type": "event",
         "attributes": {
              "profile": {
                   "$email": "[email protected]",
                   "$first_name": "John",
                   "$last_name": "Smith",
                   "$phone_number": "5551234567",
                   "$address1": "123 Abc st",
                   "$city": "Boston",
                   "$zip": "02110",
                   "$region": "MA"
              },
              "metric": {
                   "name": "Created Invoice"
              },
              "properties": {
                   "MissingInformation": ["Shipping Address Information","Shipping Method"],
                   "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": 5.00,
                       "RowTotal": 5.00,
                       "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": 4.99,
                       "RowTotal": 4.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"
                   }],
                   "Billing Address": {
                       "FirstName": "John",
                       "LastName": "Smith",
                       "Phone": "5551234567",
                       "Address1": "123 Abc st",
                       "City": "Boston",
                       "Zip": "02110",
                       "Region_code": "MA",
                       "Country": "United States",
                       "CountryCode": "US"
                   },
                   "Shipping Address": {
                       "FirstName": "John",
                       "LastName": "Smith",
                       "Phone": "5551234567",
                       "Address1": "123 Abc st",
                       "City": "Boston",
                       "Zip": "02110",
                       "Region_code": "MA",
                       "Country": "United States",
                       "CountryCode": "US"
                   }
              },
              "time": "2023-01-10T00:00:00",
              "value": 9.99,
              "unique_id": "1234"
         }
    }
}

Placed Order notifications

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 notifications

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 below for an example of what the Failed Payment payload should look like:

{
    "data": {
         "type": "event",
         "attributes": {
              "profile": {
                   "$email": "[email protected]"
              },
              "metric": {
                   "name": "Failed Payment"
              },
              "properties": {
                   "PaymentFailure": "Credit card not accepted",
                   "PaymentNextSteps": "Please use a different payment method or contact your credit card provider",
                   "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": 5.00,
                       "RowTotal": 5.00,
                       "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": 4.99,
                       "RowTotal": 4.99,
                       "ProductURL": "http://www.example.com/path/to/product2",
                       "ImageURL": "http://www.example.com/path/to/product/image2.png"
                   }]
              },
              "time": "2023-01-10T00:00:00",
              "value": 9.99,
              "unique_id": "1234"
         }
    }
}

Shipping notifications

If you have access to the relevant 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 below for an example of what a shipping notification payload should look like:

{
    "data": {
         "type": "event",
         "attributes": {
              "profile": {
                   "$email": "[email protected]"
              },
              "metric": {
                   "name": "Shipping Update"
              },
              "properties": {
                   "UpdateType": "Out for delivery",
                   "Items": [{
                       "ProductID": 1111,
                       "SKU": "WINNIEPOOH",
                       "ProductName": "Winnie the Pooh",
                       "Quantity": 1,
                       "ItemPrice": 5.00,
                       "RowTotal": 5.00,
                       "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": 4.99,
                       "RowTotal": 4.99,
                       "ProductURL": "http://www.example.com/path/to/product2",
                       "ImageURL": "http://www.example.com/path/to/product/image2.png"
                   }],
                   "Shipping Address": {
                       "FirstName": "John",
                       "LastName": "Smith",
                       "Phone": "5551234567",
                       "Address1": "123 Abc st",
                       "City": "Boston",
                       "Zip": "02110",
                       "Region_code": "MA",
                       "Country": "United States",
                       "CountryCode": "US"
                   }
              },
              "time": "2023-01-10T00:00:00",
              "unique_id": "1234"
         }
    }
}

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:

Event	Location	Description
Became Lead	Prospective customer’s profile	When someone becomes a lead or takes a specific action which qualifies them for a personal reach-out.
New Lead	Customer representative’s profile	Notify the customer representative who will take ownership of the new lead.

Like other events, add customer information to the profile 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.

{
    "data": {
         "type": "event",
         "attributes": {
              "profile": {
                   "$email": "[email protected]",
                   "$first_name": "John",
                   "$last_name": "Smith",
                   "$phone_number": "5551234567",
                   "$address1": "123 Abc st",
                   "$city": "Boston",
                   "$zip": "02110",
                   "$region": "MA",
                   "MostRecentLeadSource": "Whitepaper request form"
              },
              "metric": {
                   "name": "Became Lead"
              },
              "properties": {
                   "Action": "Filled out whitepaper request form"
              },
              "time": "2023-01-10T00:00:00",
              "unique_id": "1234"
         }
    }
}

New lead

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

{
    "data": {
         "type": "event",
         "attributes": {
              "profile": {
                   "$email": "[email protected]",
                   "$first_name": "Jane",
                   "$last_name": "Doe"
              },
              "metric": {
                   "name": "New Lead"
              },
              "properties": {
                   "LeadFirstName": "John",
                   "LeadLastName": "Smith",
                   "LeadPhoneNumber": "5551234567",
                   "LeadEmailAddress": "[email protected]",
                   "LeadAction": "Filled out whitepaper request form"
              },
              "time": "2023-01-10T00:00:00",
              "unique_id": "1234"
         }
    }
}

📘

📘

Server-side requests

Account notifications

Created account

Updated account

Updated email

Reset password

Order notifications

Created Invoice or Created Order notifications

📘

Placed Order notifications

Failed Payment notifications

Shipping notifications

Lead tracking

Became lead

New lead

Additional resources