Klaviyo (real-time)

Send a single customer to Klaviyo as soon as Amperity sees the customer interaction. Each destination performs one of three operations, and Amperity sends one request for each customer:

To send audience lists and profile attributes on a schedule rather than in real time, use the Klaviyo destination.

This connector is named Klaviyo in Amperity and sends from a real-time journey. See Real-time destinations.

Credentials

Name and description

The name and description for a credential.

Credential type

Choose “klaviyo” to use a private API key. This is the same credential type that the Klaviyo destination uses, so a credential set up for that destination can be selected here.

This connector also lists “klaviyo-oauth”, the OAuth credential type of the Klaviyo data source. Amperity cannot start an OAuth authorization from this connector. With a “klaviyo-oauth” credential, Amperity authenticates with its refresh token. Amperity’s Klaviyo OAuth authorization does not request permission to write events, so the connection test, profile_upsert, and list_remove can work, but event sends are likely to be rejected with 403 Forbidden, which fails the send without another attempt. Use a “klaviyo” credential for the event operation.

API key

Required for the “klaviyo” credential type. A private API key for your Klaviyo account.

Settings

Name and description

The name and description for a destination.

Business user access

By default a destination is available to all users who have permission to view personally identifiable information (PII).

Enable the Admin only checkbox to restrict access to only users assigned to the Datagrid Operator and Datagrid Administrator policies.

Enable the PII setting checkbox to allow limited access to PII for this destination.

Use the Restrict PII access policy option to prevent users from viewing data marked as PII anywhere in Amperity and from sending data to downstream workflows.

Operation

Required. The operation this destination performs for each customer it receives: “event”, “profile_upsert”, or “list_remove”. Every Activate node that sends to the destination uses this operation. To perform more than one operation, add one destination for each.

Note

When you save the destination, Amperity tests the connection by requesting a page of lists from Klaviyo. The test fails if the request fails for any reason; a 401 Unauthorized or 403 Forbidden response is reported as a credential error. The test does not send an event, a profile, or a list removal, so it does not check that the credential can perform the selected operation.

Activate node settings

The rest of the configuration for this connector belongs to the journey that sends to it. Add this destination to an Activate node, then configure the following fields on that node. Two nodes may send to the same destination with different targets and custom attributes. Mapped attributes are set once for the destination in the journey, so every node that sends to it uses the same mapped attributes.

target

Set on the Payload tab. The event and list_remove operations need it, and profile_upsert ignores it. Amperity does not check that it is set, and the node saves without it. A list_remove with no target sends a request with no list ID. Because Amperity treats any 404 Not Found as success for that operation, the send is likely to report success and remove nothing.

  • For event, the metric name that Amperity sends with the event.

  • For list_remove, the ID of the Klaviyo list to remove the profile from.

Attributes

Set on the Attributes tab. When you add the destination to the node, Amperity lists these four destination attribute names there. Map an Amperity attribute to each of them, whatever the destination’s operation; Amperity does not save the node’s attributes while one of them is unmapped.

  • email is the customer’s email address.

  • phone_number is the customer’s phone number. Map a value in E.164 format, such as “+15551234567”. Amperity sends the value as mapped and does not reformat it.

  • external_id is sent as the profile’s external ID. Map the Amperity ID, to link the Klaviyo profile to the Amperity profile.

  • klaviyo-profile-id is the Klaviyo internal profile ID. Amperity sends it only for list_remove, as the ID of the profile to remove from the list. Amperity never sends it as a profile attribute.

Any other attribute that you map is sent with the profile. Amperity places each one by its destination attribute name, which must match exactly, including case:

  • “email”, “phone_number”, “external_id”, “first_name”, “last_name”, “organization”, “title”, “image”, “anonymous_id”, and “_kx” are sent as the standard profile fields with those names.

  • “address1”, “address2”, “city”, “region”, “zip”, “country”, “latitude”, “longitude”, “timezone”, and “ip” are sent in the profile’s location.

  • Every other name is sent as a custom profile property with that name.

For event, the attributes that you map are sent with the event’s profile. Custom attributes, the fixed values that you add on the Custom attributes tab when you edit the node’s attributes, are sent as the event’s properties instead. For profile_upsert, custom attributes are sent with the profile like any other attribute. list_remove sends only the list ID and the profile ID.

Amperity sends date values as text. An attribute with an empty value for the customer is sent as null; Amperity does not leave it out of the request. This applies to email, phone_number, and external_id too: because all three are mapped on every node, a customer with no phone number, for example, is sent with a null phone_number.

What Amperity sends

event

Amperity sends the event with these values:

  • The metric name from target.

  • The profile, built from the mapped attributes as described above.

  • The event’s properties, from the custom attributes.

  • A time, which is the time Amperity queued the send. Amperity does not read the event time from the customer’s data.

  • A unique ID, which Amperity derives from the send. Every attempt for the same send carries the same unique ID.

profile_upsert

Amperity sends the profile, built from the mapped attributes and custom attributes. When Klaviyo responds with 409 Conflict, Amperity reports the send as successful.

list_remove

Amperity sends the list ID from target and the profile ID from klaviyo-profile-id. When Klaviyo responds with 404 Not Found, Amperity reports the send as successful, whatever the reason for the response. Confirm the list ID in target.

Amperity sends no unique or deduplication ID for profile_upsert or list_remove.

Failed sends

Amperity makes up to three attempts for each send, with a short delay before each new attempt. Within an attempt, Amperity retries each request up to five times, with increasing waits, after a connection error, a request timeout (408), a rate limit error (429), or a server error (5xx). One request can therefore be made up to 18 times for a send.

Amperity makes another attempt after these failures:

  • 429 Too Many Requests.

  • A server error, 500 or higher.

  • Any other response that is not listed below, and a request that gets no response.

Amperity does not try again after these responses, and the send fails:

  • 400 Bad Request.

  • 401 Unauthorized or 403 Forbidden. A credential that Klaviyo rejects fails every send until it is fixed. Amperity reuses its connection to Klaviyo for each credential for up to 60 minutes, so after you edit the credential, sends can keep failing for up to an hour. Choosing a different credential for the destination takes effect at once.

A send that fails all three attempts is not retried later.