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.

🚧
Using or migrating to OAuth?
When migrating from private key to OAuth, metric names should remain unchanged so that Klaviyo can brand these metrics with your icon. You should stop sending any data via private key once your users have installed your OAuth version. To learn more about branding your app’s metrics and what to avoid, read our branded app metrics guide.

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 common 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

You can use a created account event to send confirmation and welcome emails thanking a new subscriber and/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": {
      "properties": {...},
      "metric": {
        "data": {
          "type": "metric",
          "attributes": {
            "name": "Created Account"
          }
        }
      },
      "profile": {
        "data": {
          "type": "profile",
          "id": "01H81WC034AKRMQJQARPEEBHJE",
          "attributes": {
            "email": "[email protected]",
            "phone_number": "+15551234567",
            "first_name": "John",
            "last_name": "Smith",
            "location": {
              "address1": "123 Abc St",
              "city": "Boston",
              "country": "United States",
              "region": "MA",
              ...
            }
          }
        }
      },
    "time": "2023-10-15T00:00:00",
    "unique_id": "1234"
    }
  }
}

Updated account

You can trigger an updated account event when someone updates information in their account, such as their email address, name, or password. Use this event to send emails confirming updated account information, next steps for account setup, or any other information related to the customer journey.

The table below contains 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

Here’s an example of what an updated account payload looks like:

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

Updated email

To update a profile’s email address, you will need to make an additional set of requests, since Klaviyo uses email address as the primary identifier for a profile. 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

You can set up a reset password event for when a person requests to reset their password. When a person requests to reset their password, send a reset password payload with the URL of the reset password link included in the properties dictionary as shown in the example below. This event can then be used to trigger a flow email for the person to reset their password using the reset password URL.

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

Order notifications

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

Created invoice or created order notifications

Set up created invoice and created order events when there’s an incomplete order that needs customer action (e.g., a signature, size selection, setting up billing frequency, etc.) before it can be processed on your end.

📘
A created invoice event is similar to a started checkout event, an event commonly used for setting up abandoned cart flows. The type of notification you want to send depends on your business and the data you send. Note the difference between abandoned cart and invoice notifications to determine which event you can track:

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.

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).

Here's an example of what a created invoice payload should look like:

{
  "data": {
    "type": "event",
    "attributes": {
      "properties": {
        "OrderId": "1234",
        "Categories": [
          "Fiction",
          "Children"
        ],
        "ItemNames": [
          "Winnie the Pooh"
        ],
        "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"
            ]
          }
        ],
        "BillingAddress": {
          "FirstName": "John",
          "LastName": "Smith",
          "Address1": "123 Abc St",
          "City": "Boston",
          "RegionCode": "MA",
          "CountryCode": "US",
          "Zip": "02110",
          "Phone": "+15551234567"
        },
        "ShippingAddress": {
          ...
        }
      },
      "time": "2023-10-31T00:00:00",
      "value": 9.99,
      "metric": {
        "data": {
          "type": "metric",
          "attributes": {
            "name": "Created Invoice"
          }
        }
      },
      "profile": {
        "data": {
          "type": "profile",
          "id": "01GDDKASAP8TKDDA2GRZDSVP4H",
          "attributes": {
            "email": "[email protected]",
            "phone_number": "+15551234567",
              ...
            }
          }
        }
      },
    "time": "2023-10-15T00:00:00",
    "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 event for a custom platform without a pre-built Klaviyo integration.
Placed order event for a subscription-based business (without a pre-built Klaviyo integration).

Failed payment notifications

Use a 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 a failed payment payload should look like:

{
  "data": {
    "type": "event",
    "attributes": {
      "properties": {
        "OrderId": "1234",
        "PaymentFailure": "Credit card not accepted",
        "PaymentNextSteps": "Please use a different payment method or contact your credit card provider.",
        "Categories": [
          "Fiction",
          "Children"
        ],
        "ItemNames": [
          "Winnie the Pooh"
        ],
        "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"
            ]
          }
        ]
      },
      "time": "2023-10-31T00:00:00",
      "value": 9.99,
      "metric": {
        "data": {
          "type": "metric",
          "attributes": {
            "name": "Failed Payment"
          }
        }
      },
      "profile": {
        "data": {
          "type": "profile",
          "id": "01GDDKASAP8TKDDA2GRZDSVP4H",
          "attributes": {
            "email": "[email protected]"
            }
          }
        }
      },
    "time": "2023-10-15T00:00:00",
    "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": {
      "properties": {
        "OrderId": "1234",
        "UpdateType": "Out for delivery",
        "Categories": [
          "Fiction",
          "Children"
        ],
        "ItemNames": [
          "Winnie the Pooh"
        ],
        "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"
            ]
          }
        ],
        "ShippingAddress": {
          "FirstName": "John",
          "LastName": "Smith",
          "Address1": "123 Abc St",
          "City": "Boston",
          "RegionCode": "MA",
          "CountryCode": "US",
          "Zip": "02110",
          "Phone": "+15551234567"
        }
      },
      "time": "2023-10-31T00:00:00",
      "value": 9.99,
      "metric": {
        "data": {
          "type": "metric",
          "attributes": {
            "name": "Shipping Update"
          }
        }
      },
      "profile": {
        "data": {
          "type": "profile",
          "id": "01GDDKASAP8TKDDA2GRZDSVP4H",
          "attributes": {
            "email": "[email protected]"
            }
          }
        }
      },
    "time": "2023-10-15T00: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": {
      "properties": {
        "Action": "Filled out whitepaper request form"
      },
      "metric": {
        "data": {
          "type": "metric",
          "attributes": {
            "name": "Became Lead"
          }
        }
      },
      "profile": {
        "data": {
          "type": "profile",
          "id": "01H81WC034AKRMQJQARPEEBHJE",
          "attributes": {
            "email": "[email protected]",
            "phone_number": "+15551234567",
            "first_name": "John",
            "last_name": "Smith",
            "location": {
              "address1": "123 Abc St",
              "city": "Boston",
              ...
            }
          },
          "properties": {
            "MostRecentLeadSource": "Whitepaper request form"
          }
        }
      },
    "time": "2023-10-15T00: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": {
      "properties": {
        "LeadFirstName": "John",
        "LeadLastName": "Smith",
        "LeadPhoneNumber": "5551234567",
        "LeadEmailAddress": "[email protected]",
        "LeadAction": "Filled out whitepaper request form"
      },
      "metric": {
        "data": {
          "type": "metric",
          "attributes": {
            "name": "New Lead"
          }
        }
      },
      "profile": {
        "data": {
          "type": "profile",
          "id": "01H81WC034AKRMQJQARPEEBHJE",
          "attributes": {
            "email": "[email protected]",
            "phone_number": "+15551234567",
            "first_name": "John",
            "last_name": "Smith",
            "location": {
              "address1": "123 Abc St",
              "city": "Boston",
              ...
            }
          },
          "properties": {
            "MostRecentLeadSource": "Whitepaper request form"
          }
        }
      },
    "time": "2023-10-15T00:00:00",
    "unique_id": "1234"
    }
  }
}

Set up API-based transactional events

📘

🚧
Using or migrating to OAuth?

📘

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

📘

🚧Using or migrating to OAuth?

📘

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

🚧
Using or migrating to OAuth?