Klaviyo

Klaviyo is the messaging tool Toki works with most closely. Once connected, every Toki event lands on the customer's Klaviyo profile as a metric, together with their up-to-date loyalty properties, so you can build Klaviyo flows and segments on loyalty data. The same connection powers a reward for Klaviyo form sign-ups, the phone step of the newsletter reward, referral invites sent through Klaviyo, Klaviyo lists and segments as conditions, and Klaviyo coupon codes in the wallet.

What you need from Klaviyo

Toki asks for two keys. Both live on the API keys tab of your Klaviyo account: in Klaviyo, click your account name in the lower left, open Settings, then API keys. Only Klaviyo Owners and Admins can open this tab.

Field in Toki	What it is	Where to find it
Public API Key / Site ID	Klaviyo's public key: a short code of six letters and numbers. Klaviyo also calls it the Site ID, and there is one per account. It is safe to share.	Shown on the API keys tab.
Private API Key	A key that starts with `pk_` and lets Toki read from and write to your account. Treat it like a password.	Create one on the API keys tab (steps below). Klaviyo shows it once, so copy it right away and keep it somewhere safe, such as a password manager.

Create the private key

On the API keys tab in Klaviyo, click Create Private API Key.
Name the key, for example "Toki".
Choose the scope: Full, or Custom with at least the access listed below.
Click Create and copy the key.

A key's scope is fixed once it is created. To give Toki more access later, create a new key and paste it into Toki.

Access the private key needs

Klaviyo area	Access	Toki uses it to
Events	Full (`events:write`)	Send Toki events to customer profiles.
Profiles	Full (`profiles:read`, `profiles:write`)	Find a customer's Klaviyo profile and add a phone number to it.
Subscriptions	Full (`subscriptions:write`)	Subscribe customers through the Newsletter sign up reward.
Lists	Full (`lists:read`, `lists:write`)	Offer your Klaviyo lists as segment and tier conditions, check who is on them, and add phone numbers to the list you set on the Newsletter sign up reward.
Segments	Read (`segments:read`)	Offer your Klaviyo segments as segment and tier conditions and check who is in them.
Coupons and Coupon codes	Read (`coupons:read`, `coupon-codes:read`)	Show Klaviyo coupon codes in the wallet. Only needed with Enable Coupons Integration on.

The names in parentheses are Klaviyo's scope names for that access.

Connect Klaviyo

In the Toki app, open Integrations.
On the Klaviyo row, click Install.
On the Install Klaviyo page, paste your Public API Key / Site ID and Private API Key.
Turn on the switches you want (see below).
Click Save in the bar at the top of the page.

Toki checks the keys as you save. The Site ID is checked against your Klaviyo account; the private key is checked for its format. Problems show under the field, and nothing is saved until you fix them. Toki relies on the private key's access later, each time it sends an event or reads a list, so set the key's scope before you connect.

Right after a successful save, Toki sends one sample of every Toki event to your Klaviyo account. That makes all the Toki metrics exist in Klaviyo straight away, so you can pick them as flow triggers before any customer has done anything.

The samples, and the Site ID check, go to a test profile, "Test Toki-Klaviyo Integration User" (toki-klaviyo-integration@gmail.com), so expect to see it in your Klaviyo account. Toki writes to it when you save your Klaviyo settings and doesn't use it for anything else. Each save records the samples again, so the profile can enter flows that start from a Toki metric unless a flow filter leaves it out. The samples cover every event in Toki's catalog, including a few that Toki keeps for its own automations; Email and SMS events lists the events sent for your customers.

The install, manage, and uninstall flow is the same for every integration; see Integrations and your API key.

The two switches

Switch	What it does when it is on
Enable Auto Profile Creation	Every Klaviyo form submitted on your storefront creates a Toki member for the email address entered, if that person is not a member yet. With the switch off, Toki only reacts to forms that are connected to a Klaviyo: Sign up reward.
Enable Coupons Integration	Coupon codes Klaviyo has assigned to a customer appear in that customer's wallet. See "Klaviyo coupons in the wallet" below.

Change or disconnect

To change the keys or switches, click Manage on the Klaviyo row, edit the Manage Klaviyo page, and click Save. The private key is masked; paste a new one to replace it.

To disconnect, click Uninstall on the row and confirm. Toki deletes the keys it stored and stops sending events. Nothing changes in your Klaviyo account: the metrics and profile properties already sent stay there.

What Toki sends to Klaviyo

Each time something happens to a customer in Toki, such as earning points, reaching a tier, or redeeming a reward, Toki sends it to Klaviyo as an event. In Klaviyo you see it as a metric named after the event, for example Toki Points Earned, on the profile with the customer's email address. When Toki has a valid phone number for the customer, it is included too.

Every event also carries the customer's current loyalty data, which Klaviyo stores as custom profile properties that all start with toki_, such as toki_point_balance, toki_tier_name, and toki_referral_link. Toki sends them with every event, not just the ones that changed.

The complete list of events, their properties, and the profile properties is in Email and SMS events.

Toki sends events for customers who have an email address in Toki and are members of the store. Suspended members get no events while the suspension lasts.

Event names that differ in Klaviyo

Most events keep their Toki name with a "Toki" prefix: Points Earned in a Toki campaign or workflow is the metric Toki Points Earned in Klaviyo. Four events have their own Klaviyo names:

In Toki	In Klaviyo
Membership Unlocked	Toki Tier Earned
Membership Lost	Toki Tier Lost
Referred a Friend	Toki Referral Completed
Voting Activity Completed	Toki Completed Voting Activity

One event exists because of Klaviyo: Toki Klaviyo Submission fires when a customer submits a Klaviyo form on your storefront (see "Klaviyo: Sign up reward" below). It goes to Klaviyo and to your Toki campaigns and workflows, and to no other messaging tool. It carries toki_klaviyo_form_id, the ID of the form, and toki_magic_link, a sign-in link to the customer's wallet that is valid for 24 hours.

How properties look in Klaviyo

A few properties are shaped for Klaviyo so you can use them in segments:

toki_wishlist_product_ids, toki_wishlist_variant_ids, toki_wishlist_product_handles, and toki_reviewed_product_ids arrive as lists, so a "contains" condition works on them.
toki_points_expirations arrives as structured data rather than one line of text.
A property that Toki sends without a value arrives as - (a dash). A customer without a tier, for example, has toki_tier_name equal to -.

Rewards and features that use Klaviyo

Klaviyo: Sign up reward

This reward gives customers points for submitting one of your Klaviyo forms on your storefront. In the catalog it reads "Customers earn store credit for signing up to your Klaviyo list."

Open Loyalty. In Ways to Earn, click Add new activity.
Under Integrations, pick Klaviyo: Sign up. If the catalog shows "For this reward, you need to install an external integration", click Install integration, connect Klaviyo, and come back.
In the Rules card, fill in the fields below.
Set up the reward, set Status to Active, and click Save.

Field	What it does
Redirect URL	The page on your store where the Klaviyo form lives, as a path such as `/pages/newsletter`. The reward's Complete button in the wallet opens this page.
Use a separate redirect URL for each shop	Appears when you run more than one shop with Toki. Turn it on to get one Redirect URL field per shop, so customers in each shop land on the right page.
Form IDs	The ID of the Klaviyo form that counts for this reward. At least one is required. Click Add Form ID to accept more forms; a submission of any of them completes the reward. To find a form's ID, open the form in Klaviyo's form editor: it's the six-character code at the end of the page address.

Here is what happens for the customer:

In the wallet, the reward shows "Action must be taken on site" and a Complete button. Complete opens the Redirect URL page in a new tab.
The customer fills in the Klaviyo form on that page.
Toki's theme app embed notices the submission, matches the form's ID to your reward, and completes it. Completions of this reward type are approved automatically.

Customers do not have to start from the wallet: any submission of that form on your storefront counts. Toki creates a member for the email address entered if there is none yet. If the form only asks for a phone number, Toki looks up the email on the matching Klaviyo profile and uses that. Each submission also fires Toki Klaviyo Submission, so you can welcome the customer from a Klaviyo flow, an event-triggered campaign, or a workflow.

The theme app embed has to be on in your theme for Toki to see the form; see Install Toki. If your Klaviyo form is a pop-up rather than a page of its own, chat with us and we'll set it up with you.

Newsletter sign up reward

The Newsletter sign up reward (under Other in the catalog) has its own form in the wallet. With Subscription source set to Toki form and Klaviyo connected, Toki passes the sign-up on to Klaviyo:

Step	What Toki does in Klaviyo
Email step (always on)	When the customer completes the reward, Toki subscribes their email address to email marketing in Klaviyo.
Phone step	Tick Phone step ("Enables the phone confirmation step of the form.") and paste the Klaviyo List ID of the list that should receive the number. The customer enters their phone number and clicks Submit. Toki adds the number to their Klaviyo profile, creating the profile if needed, and subscribes it to SMS marketing on that list.

During the phone step the wallet shows "Please check your phone for a confirmation message." Whether a confirmation text goes out depends on the list's opt-in setting in Klaviyo: on a double opt-in list, Klaviyo texts the customer and subscribes the number once they confirm; on a single opt-in list, Klaviyo subscribes it right away. Toki completes the reward once Klaviyo reports the number as subscribed, and the customer sees "Thank you for signing up for our newsletter!"

To find a list's ID in Klaviyo, open Lists & Segments, click the list, and open its Settings tab: the list ID is near the top of the page. It is also the short set of letters and numbers in your browser's address bar while you view the list.

Referral invites sent through Klaviyo

On a Refer a friend to purchase reward, the Rules card shows a Send invite via choice once Klaviyo is connected: Default or Klaviyo. It controls what happens when a customer invites a friend by email from the wallet.

Option	What happens
Default	The customer's own email app opens with the subject, the message, and their referral link filled in. They send it themselves.
Klaviyo	The wallet shows "Email sent successfully". Toki creates a member for the friend's email address, links the friend to the referrer, and sends the Toki Send Refer A Friend Invite event for the friend, with the referrer's name, email, and link and the invite's subject and message. A Klaviyo flow on that metric delivers the invite in your own design.

The same event is a trigger for event-triggered campaigns and workflows, so you can send the invite from Toki instead. For the rest of the referral setup, see Referral rewards.

Klaviyo lists and segments as conditions

With Klaviyo connected, segments and membership tiers get the condition Klaviyo segment ("Customers should be in the selected Klaviyo segment / list"). Pick one of your Klaviyo lists or segments in Klaviyo Segment; the dropdown loads them straight from Klaviyo. Toki checks who is on the list or in the segment right after you save, and again once an hour. With each check, Toki also creates a member for everyone on the list or in the segment who has an email address and isn't a member yet. The condition keeps working as long as the list or segment exists in Klaviyo. Details are in Segment conditions and Tier conditions.

Klaviyo coupons in the wallet

Turn on Enable Coupons Integration and customers see the coupon codes Klaviyo has given them next to their loyalty coupons, under Your Coupons in the wallet, with the same one-tap copy or apply as any other coupon.

Each time a customer opens their coupons, Toki looks up their Klaviyo profile by email and pulls in the codes that are assigned to that profile and still valid, meaning their expiration date is in the future. To be sure a code shows up, give it an expiration date in Klaviyo. A code appears when it exists in your Shopify store as a discount code: an amount off, a percentage off, free shipping, or Buy X Get Y. The coupon's description from Klaviyo becomes the coupon's title in the wallet, and the expiry date from Klaviyo is shown with it. A code that has already been used on an order is marked as used.

To get codes assigned to profiles, use Klaviyo's unique coupon codes in your Klaviyo flows and campaigns.

Other places you will see Klaviyo

Gift card delivery set to External sends the gift card events to Klaviyo; see Gift card delivery.
The Send Custom External Event workflow action can send an event you name to Klaviyo; see Workflow actions.
Survey, quiz, and poll answers reach Klaviyo as profile properties named after the activity's Alias; see Creating rewards.
Customers' wallet pass download links reach Klaviyo as toki_apple_download_link and toki_google_download_link; see Wallet passes.
Moving reviews from Klaviyo to Toki is a CSV import that works without this connection; see Import reviews.

Typical setups built on Toki events

You build the flows and segments in Klaviyo; Toki supplies the metrics and properties. These are the combinations merchants use most:

You want to…	Trigger on this Klaviyo metric	Useful properties
Welcome new members	Toki Account Created	Profile properties `toki_referral_link` and `toki_point_balance`
Congratulate a customer on a new tier	Toki Tier Earned	Event property `toki_tier_name`; profile property `toki_tier_rewards`
Win back a customer who dropped out of a tier	Toki Tier Lost	Event property `toki_tier_name`
Confirm points as they come in	Toki Points Earned	Event properties `amount` (points just earned), `toki_point_balance`, and `toki_points_earned` (lifetime total)
Deliver a discount code a customer earned	Toki Reward Created	Event properties `toki_code`, `toki_type`, and `toki_value`
Send referral invites in your own design	Toki Send Refer A Friend Invite	Event properties `toki_referrer_name`, `toki_referrer_link`, `toki_subject`, and `toki_message`
Thank a customer whose friend placed an order	Toki Referral Completed	Event properties `toki_referee_email` and `toki_order_amount`
Follow up on a Klaviyo form sign-up with a wallet link	Toki Klaviyo Submission	Event property `toki_magic_link` (valid for 24 hours)
Remind customers about wishlisted products	Toki Wishlist Item Added	Event properties `toki_product_id`, `toki_variant_id`, and `toki_label`
Follow up on survey or quiz answers	Toki Completed Voting Activity	Profile properties `toki_<activity alias>_<field alias>`, one per answer
Add wallet pass links to any email	Any	Profile properties `toki_apple_download_link` and `toki_google_download_link`

Use Toki Account Created for welcome flows: it fires when the customer's loyalty account is created, so the flow runs for new members only.

Start a flow from a Toki metric

In Klaviyo, create a new flow.
Choose Metric as the trigger.
Pick the Toki metric, for example Toki Tier Earned.

A metric-triggered flow runs every time the metric is recorded for a customer, unless you add flow filters. A flow keeps the metric you pick; to start the same flow from a different metric, clone it in Klaviyo.

To put an event property into a flow email, open the email, click Edit next to Template, click Preview & test, and click the property in the Event Properties menu to copy it. Then paste it into your email. In a text message, click Edit next to Content, click Preview & test, and copy the property from the All properties menu. Event properties work only in flows that start from a metric, and they have to be copied exactly, capital letters included.

Profile properties work in any email or text: type the property with Klaviyo's lookup tag, for example {{ person|lookup:'toki_point_balance' }} for the points balance.

Troubleshooting

The keys are not accepted when you save. "Invalid Klaviyo Public API Key format" means the value is not a six-character Site ID; check that you did not paste the private key there. "Invalid Klaviyo Private API Key format" means the private key does not start with pk_. "Bad Request" or "Failed to track test profile" under the Site ID means Klaviyo did not accept it: copy it again from the API keys tab.

Events or toki_ properties are not showing up in Klaviyo. Open Integrations and check that the Klaviyo row shows Installed; Toki only sends events to connected tools. Properties travel with events, so a customer who has not triggered any event since you connected has no toki_ properties yet. If you want every member's properties in Klaviyo right away, chat with us and we'll sync them for you. The customer needs an email address in Toki and must not be suspended. If you created the private key with a Custom scope, make sure it has the access listed above.

A Klaviyo: Sign up reward is not completing. Check that the form's ID matches one of the Form IDs on the reward, that the reward's Status is Active, and that the Toki theme app embed is on in your theme. The form needs to collect an email address, or a phone number that already belongs to a Klaviyo profile with an email.

A Klaviyo list or segment is missing from the condition dropdown. The dropdown loads your lists and segments from Klaviyo with the private key. If they don't appear, check that the key has read access to Lists and Segments.