Send query results to Klaviyo¶

Klaviyo is an email platform for targeting, personalizing, measuring, and optimizing email and Facebook campaigns.

Note

This destination uses the Klaviyo REST API .

Amperity uses the Update Profile endpoint in the Klaviyo API to send customer profile attributes to Klaviyo.

Review the rate limits that are applied to endpoints in the Klaviyo REST API to manage customer profiles.

Before sending a set of customer profiles to Klaviyo, and to help set expectations, you should review the rate limits and estimate the amount of time required to complete the process of adding your set of customer profiles to Klaviyo.

If you don’t want to wait to load customer profiles, you may instead use the SFTP import tool process. This approach is efficient and quick. It uses the built-in SFTP connector in Amperity and is capable of importing large sets of customer profiles.

The CSV file that is imported to Klaviyo has specific requirements on formatting and must include one (or more) of the following fields: “Email”, “PhoneNumber”, and/or “ExternalID”. When these fields are present in the CSV file they must have those exact names.

This topic describes the steps that are required to send CSV files to Klaviyo from Amperity:

Build a query
Add orchestration
Run orchestration

Note

Klaviyo must be enabled before you can configure an orchestration to send query results. Ask your DataGrid Operator or Amperity representative to enable Klaviyo for your tenant.

Build query¶

To send query results to Klaviyo you must know which type of audience list will be updated by Amperity. There are two types:

Email address only
Email address + customer profiles

Email address only¶

The default audience list in Klaviyo requires only an email address. This requires a simple SELECT statement that returns only the Amperity ID and its associated email address:

SELECT
  ,amperity_id AS "Amperity ID"
  ,email AS "Email"
FROM Customer360

Email address + customer profiles¶

You can send results to Klaviyo that include customer profiles along with their email address, such as first and last names, phone numbers, and zip codes. Review the list of customer profile parameters your brand can send to Klaviyo.

For example:

SELECT
  amperity_id AS "external_id"
  ,given_name AS "first_name"
  ,surname AS "last_name"
  ,address AS "address1"
  ,address2 AS "address2"
  ,city
  ,state AS "region"
  ,postal AS "zip"
  ,country
  ,email AS "email"
  ,phone AS "phone_number"
  ,company AS "organization"
FROM Merged_Customers mc

You can use a LEFT JOIN to add parameters from the Unified Transactions table, such as the most recently purchased product and the date and time of that purchase, similar to:

  ,order_datetime AS "last_event_date"
  ,product AS "product"
  ...
FROM Merged_Customers mc
LEFT JOIN Unified_Transactions ut ON mc.amperity_id = ut.amperity_id

where last_event_date is a built-in parameter and product is an example of sending a custom parameter to Klaviyo.

Important

This option requires the Use full profile to update list setting to be enabled in the data template used to send query results to Klaviyo.

Add orchestration¶

An orchestration defines the relationship between query results and a destination, including the location to which those query results will be sent and the frequency at which the orchestration will be run.

To add an orchestration

From the Destinations tab, click Add Orchestration. This opens the Add Orchestration dialog box.
From the Object Type drop-down, select Query.
From the Object drop-down, select the query for which results will be sent to Klaviyo.
From the Destination drop-down, select a destination that is configured for sending data to Klaviyo.
From the Data Template drop-down, select a data template.
Verify all settings.
Set the workflow to Manual. (You can change this to automatic later, after verifying the end-to-end workflow.)
Click Save.

Run orchestration¶

Run the orchestration manually to validate that it works.

To run the orchestration

From the Destinations tab, under Orchestrations, open the menu for the Klaviyo orchestration, and then select Run.
The Status column for the orchestration will update to say “Waiting to start…”, after which the notifications pane will update to include a notification that shows the current status.
When the orchestration has run successfully, the status is updated to “Completed”.

Customer profile parameters¶

The following table describes the parameters that may be sent to Klaviyo.

Amperity uses the Update Profile endpoint in the Klaviyo API to send customer profile attributes to Klaviyo.

The list of customer profile parameters supported by Klaviyo are described in the following table. Parameters are listed alphabetically, but may be returned in any order.

Field name	Description
address1	Optional The address that is associated with the location of an individual customer record. For example: 123 Main Street.
address2	Optional Additional address information, such as an apartment number or a post office box, that is associated with the location of an individual customer record. For example: Apt #9.
city	Optional The city that is associated with the location of an individual customer record.
country	Optional The country that is associated with the location of an individual customer record.
email	Required The email address that is associated with an individual customer record. A customer record may be associated with multiple email addresses. Important An email address is used by Klaviyo to generate a unique customer identifier for each customer profile that exists within Klaviyo. This email address is most often found in the email field in the Merged Customers table, but may be located elsewhere depending on how your brand has configured your customer 360 database and depending on the downstream use cases your brand wants to enable within Klaviyo.
external_id	Optional A unique identifier that associates Klaviyo profiles with customer profiles that exist within an external system. For example, a unique ID for a point-of-sale system or the Amperity ID.
first_name	Optional The first name that is associated with an individual customer record.
image	Optional A URL that points to the location of a profile image for this customer profile.
ip	Optional An IP address that is associated with this customer profile.
last_event_date	Optional A timestamp for an event that is associated with this customer profile. For example, the date and time of the most recent transaction from your brand’s website or store.
last_name	Optional The last name that is associated with an individual customer record.
latitude	Optional A latitude coordinate that may be used to define location-based segments in Klaviyo. Note This value should have a precision of four decimal places.
longitude	Optional A longitude coordinate that may be used to define location-based segments in Klaviyo. Note This value should have a precision of four decimal places.
organization	Optional The company, typically an employer or small business, that is associated with an individual customer record.
phone_number	Optional The phone number that is associated with an individual customer record. A customer record may be associated with multiple phone numbers. Note A phone number must be in E.164 format , which represents a phone number as a number up to fifteen digits in length (without spaces) that starts with a + symbol. For example: +12061234567.
properties	Optional A series of custom properties represented as key/value pairs for additional data that your brand wants to associate with this customer profile. For example, a store ID or the name (or SKU) of the most recent product purchase associated with this customer profile.
region	Optional The state or province that is associated with the location of an individual customer record.
timezone	Optional The name of a timezome. Klaviyo recommends using the name of a timezone in the IANA Time Zone Database .
title	Optional The title that precedes a full name that is associated with an individual customer record. For example: Mr., Mrs, and Dr.
zip	Optional The zip code or postal code that is associated with the location of an individual customer record.