> For the complete documentation index, see [llms.txt](https://docs.shopwaive.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.shopwaive.com/shopify/email-and-campaigns/klaviyo-email-and-sms.md). # Klaviyo Keep each customer's Shopwaive balance on their Klaviyo profile as shopwaive\_balance, then use it in Klaviyo emails, segments and flows Klaviyo balance sync sends each customer's Shopwaive balance to their Klaviyo profile and keeps it current. You can then show the balance in Klaviyo emails and SMS, build segments on it, and trigger flows from those segments.

The Klaviyo card in Shopwaive, connected and up to date

{% hint style="info" %} Klaviyo balance sync is available on Shopify. It replaces the earlier Klaviyo integration, which used a Klaviyo list and properties such as `$shopwaive_credit`. If that integration is still switched on for your store, ask Shopwaive support to switch it off before you connect. See [If you used the earlier Klaviyo integration](#if-you-used-the-earlier-klaviyo-integration). {% endhint %} ## What it does * **One profile property.** Shopwaive writes `shopwaive_balance` on each customer's Klaviyo profile, as a number. Nothing else is written: no lists, no events or metrics, and no other properties. Your other profile properties are left untouched. * **Kept current.** When a balance changes in Shopwaive, the new value usually reaches Klaviyo within about a minute. * **Profiles are created.** A customer who has a Shopwaive account but no profile in Klaviyo is added as a profile, matched by email address. This includes customers whose balance is 0. * **The number your customer sees.** The value follows the theme you chose in Shopwaive under **Settings** > **Theme** (visible to the store owner/admin role), in the **Type** setting: * **Balance** (the default): money to two decimals. A stored balance of 55.32343 is sent as 55.32. * **Loyalty and Rewards**: whole points, multiplied by the Theme tab's **Multiplier for display** when it is above 1. The redemption multiplier is not used here. A stored balance of 24.496 is sent as 25. If you change the theme later, every balance whose number changes in the new form is sent again. This starts within about a minute and runs at the initial-sync rate. Only customers with a valid email address and a balance row in Shopwaive are synced; a balance of 0 is sent as 0. If one email address owns more than one balance row in Shopwaive, the larger balance is sent, never the sum. Shopwaive sends the value as a number, so a balance of 55.30 is sent and shown as 55.3. {% hint style="info" %} Shopwaive sends the number only. Add the currency symbol or the word "points" in your Klaviyo template. {% endhint %} ## Before you start * You need a Klaviyo account. * You will create a private API key in Klaviyo with two permission scopes. Nobody at Shopwaive needs access to your Klaviyo account. * At least one customer must have an account in Shopwaive. Connecting is refused when there is nothing to sync. * The first sync covers every customer who has a Shopwaive account, including those whose balance is 0. Each one who is not in Klaviyo yet is added as a profile. Balances above 1 are sent first; balances of 1 or less, including 0, are sent last. Klaviyo counts every profile it can email towards your plan's active profiles, including people who never subscribed to marketing, so a large first sync can move you into a higher pricing tier. Check your plan's allowance before you connect. Klaviyo lets you suppress profiles you don't intend to email, and suppressed profiles don't count towards your plan. * Klaviyo balance sync is switched on per store by Shopwaive. If the card says it is not enabled for your store yet, contact support. ## Connect Klaviyo ### Step 1: Create a private API key in Klaviyo 1. In Klaviyo, open **Settings**, then **API keys**, and choose **Create Private API Key**. 2. Name it "Shopwaive balance sync" and choose **Custom Key**. Add the following permission scopes, and leave everything else at No Access: * **Accounts: Read** * **Profiles: Full Access** 3. Create the key and copy it.

Klaviyo's Create Private API Key form: the name, Custom Key, and Accounts set to Read Access

Further down the same list, Profiles set to Full Access

{% hint style="warning" %} Klaviyo shows a private key only once and does not let you add scopes to an existing key. If a key is missing a scope, create a new one. {% endhint %} ### Step 2: Paste the key in Shopwaive 1. In your Shopify admin, open Shopwaive, then **Settings** > **Integrations**. 2. In the Klaviyo card, paste the key into **Klaviyo private API key** and click **Connect Klaviyo**.

Paste your Klaviyo private API key and click Connect Klaviyo

Shopwaive checks the key with Klaviyo. The card then reads "Connected to" followed by your Klaviyo account name and the key's fingerprint, for example `pk_…af74`. Only the first three and last four characters of the key are ever shown. The key is stored encrypted and is never sent back to your browser. {% hint style="info" %} Paste the key into Shopwaive yourself. Do not email it to support. {% endhint %} ## What the card shows The badge at the top right of the card is the state of the sync. | Badge | Meaning | | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Initial sync in progress** | Shopwaive is sending every existing balance to Klaviyo. The card reads "Syncing N existing customer balances to Klaviyo at 5 a second, about X in total", then how many have been sent so far and how long is left. It refreshes on its own. | | **Up to date** | The initial sync is complete and balance changes now reach Klaviyo within about a minute. The card reads "N balance updates sent to Klaviyo since connecting" and the time of the last sync. N counts updates, not customers. When changes are queued, it also shows how many are waiting. | | **Needs a new key** | Klaviyo rejected the key, or the key lost its Profiles scope. See [Replacing a key](#replacing-a-key). | | **Paused** | Shopwaive support paused the sync, or the earlier Klaviyo integration was switched on for this store. See [If you used the earlier Klaviyo integration](#if-you-used-the-earlier-klaviyo-integration). | | **Removing balances** | At your request, Shopwaive support is removing `shopwaive_balance` from your profiles. You can disconnect when it finishes. | The initial sync sends up to 5 balances a second. Shopwaive works in runs of about 100 seconds, one every two minutes, so the delivered rate is nearer 4 a second. The card's "about X in total" is an estimate at the top rate; the "left" figure is the one to watch. Rough times: | Balances | Initial sync | | -------- | ------------------- | | 300 | a couple of minutes | | 3,000 | about 12 minutes | | 10,000 | about 40 minutes | | 100,000 | about 7 hours | ## Wait for the first sync before you make a flow live Build your segment and flow while the initial sync runs, but keep the flow's messages in Draft until the badge reads **Up to date**. Each balance the first sync writes is a change to that profile. A customer whose new value meets your segment's condition joins the segment at that moment. A live flow triggered by that segment would then start for every such customer as their balance arrives. That could be thousands of customers in one afternoon. Two Klaviyo rules matter here: * A segment-triggered flow starts only for profiles that newly qualify. Customers already in the segment when you turn the flow on are not messaged. To include them, use Klaviyo's **Add past profiles** option on the flow's trigger. * A message in Draft queues nobody. Profiles that entered the flow while a message was in Draft are not messaged when you later set it to Live. ## Use the balance in Klaviyo ### In an email or SMS Use `{{ person.shopwaive_balance }}` anywhere in a template, including the subject line: ``` You have ${{ person.shopwaive_balance }} to spend. ``` For a Loyalty and Rewards store: ``` You have {{ person.shopwaive_balance }} points. ``` The number is sent as it is, so a balance of 55.30 prints as 55.3. To add thousands separators, or to show what a points balance is worth in money, use Klaviyo's own filters. These render correctly: ``` {{ person.shopwaive_balance|floatformat:"0g" }} 1456 becomes 1,456 {{ person.shopwaive_balance|floatformat:2 }} 55.3 becomes 55.30 {{ person.shopwaive_balance|divide:66.67|floatformat:3 }} points divided by your redemption rate ``` The quotation marks around `"0g"` are required. If you convert points to money, the rate is your own redemption multiplier from Shopwaive; Klaviyo cannot read it, so update your templates if you change it. Klaviyo does not support the `intcomma` filter. Tags are case-sensitive, so type the property name exactly. A balance of 0 renders as 0. A profile the sync has never written has no property and renders as empty text. {% hint style="warning" %} Do not apply Klaviyo's `round` filter to `shopwaive_balance`. Shopwaive already rounds the value the way your store shows it. On a Balance store the value carries cents, and `round` drops them, so 55.32 would print 55. {% endhint %} ### In a segment 1. In Klaviyo, open **Audience** > **Lists & segments** and create a segment. 2. Choose the condition **Properties about someone**, pick `shopwaive_balance`, and set the operator and value. For example, for customers with a balance of at least 100, use the condition `shopwaive_balance` **is at least** 100 with the value type set to Number. 3. Save the segment. Klaviyo fills it in the background, which can take a few minutes. `shopwaive_balance` appears in the segment builder once the sync has written it to at least one profile, so create the segment after you connect. ### In a flow 1. In Klaviyo, open **Flows**, click **Create flow**, and choose **Build your own**. 2. Choose the trigger **Added to segment** and pick the segment you built. 3. Set the re-entry rule. With **Allow re-entry**, a customer who drops below your threshold and later earns above it enters the flow again. 4. Add your email or SMS. Set it to Live only after the initial sync is complete. A "you have a balance to spend" reminder is a good first flow. {% hint style="warning" %} Klaviyo refreshes segment membership on its own schedule, which can take several minutes after a balance changes, and in our testing sometimes longer. A flow triggered by **Added to segment** only starts for someone joining, so a customer whose balance falls is not messaged by it. If your flow's message shows the balance, add the same condition as a flow filter as well: Klaviyo re-checks a flow filter before it sends, so a customer whose balance has since dropped is skipped. {% endhint %} ### Add a time delay before an email that shows a balance A balance change usually reaches Klaviyo within about a minute. Shopwaive deducts a redeemed balance when Shopify reports the order as paid, which can be a few minutes after checkout. If a flow sends an email right after an order or a balance change, add a **Time Delay** of at least 10 minutes before it. The email then shows the new number. ### Smart Sending Klaviyo's Smart Sending skips a message when the customer was emailed recently, and a skipped message is not sent later. Decide per message whether to keep it on. The sync itself never sends messages, so Smart Sending has no effect on syncing. ## Timing * **One change**: usually within about a minute. Shopwaive checks for changes once a minute. * **Many changes at once**, such as a bulk import or a bulk adjustment: up to 5 balances a second, nearer 4 a second delivered. A few hundred changes land within a couple of minutes, 3,000 take about 12 minutes, and 10,000 about 40 minutes. A single change made during a large batch waits behind it. * **The first sync**: the same rate. See the table above. * Only a changed value is sent. An unchanged balance is not sent again. Shopwaive stays within Klaviyo's API rate limits, which your Klaviyo account shares with every other integration you run, and slows down when Klaviyo asks it to. ## Keeping it in sync * **Once a day**, in the hour after midnight UTC, Shopwaive compares every balance with the value it last sent and re-sends any difference. * **Then it reads Klaviyo back.** In the following hour (about 1:00 UTC) Shopwaive reads `shopwaive_balance` from your profiles and compares each value with the balance in Shopwaive. Any value that differs is put back. A value edited by hand in Klaviyo, or overwritten by another integration, is put back. If the profile itself is gone, because it was deleted in Klaviyo or absorbed by a profile merge, Shopwaive does not re-create it: that would undo something you did on purpose. The customer's balance reaches Klaviyo again the next time it changes. The read-back runs only while the badge reads **Up to date** and nothing is waiting. Treat `shopwaive_balance` as read-only in Klaviyo. * **A removed balance goes to 0.** If a customer's account is deleted in Shopwaive, their profile gets a `shopwaive_balance` of 0. The property itself is not removed. * **A theme change re-sends what changed.** If you switch between the Balance and Loyalty and Rewards themes, every balance whose number changes in the new form is sent again. ## Replacing a key If Klaviyo stops accepting the key, for example because it was deleted in Klaviyo, the badge changes to **Needs a new key** and the card says why: * "Klaviyo rejected the key. It may have been deleted in Klaviyo. Paste a new key for the same Klaviyo account below." * "The key can no longer update profiles. Paste a new key with Profiles: Full Access below." Create a new key with the steps in [Step 1](#step-1-create-a-private-api-key-in-klaviyo), paste it into the card, and click **Save new key**. For the same Klaviyo account, syncing picks up where it left off. Nothing already in Klaviyo is sent again. A catch-up pass sends anything that changed while the sync was stopped. A key for a different Klaviyo account is refused while a connection exists. Disconnect first, then connect the other account. While the badge reads **Paused** the card shows no key field. Only Shopwaive support can resume a paused sync. ## Disconnecting Click **Disconnect Klaviyo** on the card. Shopwaive deletes the key and stops sending at once. The `shopwaive_balance` values already on your profiles stay there. Disconnecting changes nothing in Klaviyo. If you want the property removed from your profiles, contact Shopwaive support **before** you disconnect. Removal uses the connection to reach your profiles, so it cannot run after a disconnect. While it runs, the badge reads **Removing balances** and the Disconnect button is disabled. When it finishes, the badge returns to what it read before the removal, normally **Up to date** and the card's usual sync message reappears (ignore it; the values have been removed). The Disconnect button is enabled again. Disconnect then. If you connect again later, the initial sync runs again from the beginning. ## If you used the earlier Klaviyo integration Shopwaive's earlier Klaviyo integration subscribed customers to a Klaviyo list and wrote properties beginning `$shopwaive_` (for example `$shopwaive_credit`, `$shopwaive_action`, `$shopwaive_previous`, `$shopwaive_currency`, `$shopwaive_expirationdate`, `$shopwaive_expires`, `$shopwaive_code`, `$shopwaive_offer` and `$shopwaive_offerexpirationdate`). Klaviyo balance sync replaces it, and Shopwaive is switching the earlier integration off store by store. Until Shopwaive support switches it off for your store, it keeps writing those properties in their old form (a text value such as "24.50"). Any old values stay on your profiles as they were. Do not use them in new segments or templates. Rebuild your flows on `shopwaive_balance` and a segment, as described above. The earlier integration has no switch in Shopwaive Settings any more. If you ever entered a Klaviyo key in the older Shopwaive dashboard's Klaviyo flows panel, or are not sure, ask Shopwaive support to check. Have it switched off **before** you connect. Shopwaive pauses balance sync when it sees the earlier connection write to a customer's balance, but do not rely on that as a safety net: have it switched off first. The badge changes to **Paused** and the card reads "Paused because an older Shopwaive Klaviyo connection was switched on for this store. Contact Shopwaive support." Pasting a key does not resume it. Support resumes balance sync after switching the earlier connection off. ## Troubleshooting | The card says | What to do | | ------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | That isn't a Klaviyo private API key. Private keys start with pk\_. | You pasted a public key or something else. Copy the private key from Klaviyo. Private keys start with `pk_`. | | Klaviyo didn't accept this key. Check that you copied the whole private API key. | The key is incomplete or was deleted in Klaviyo. Create a new one. | | This key can't read your Klaviyo account. Create it with Accounts: Read access. | The key is missing the Accounts: Read scope. Scopes cannot be added to an existing key, so create a new one with both scopes. | | This key can't update profiles. Create it with Profiles: Full Access. | The key is missing the Profiles: Full Access scope. Create a new one with both scopes. | | Shopwaive has no customer balances for this store yet, so there's nothing to sync. | Give at least one customer a balance, then connect. | | Klaviyo balance sync isn't enabled for this store yet. Contact Shopwaive support to turn it on. | The sync is switched on per store. Contact support. | | Klaviyo didn't respond as expected. Try again in a minute. | Klaviyo did not answer, or answered with an error. Wait a minute and try again. | | This store is already connected to (account). Disconnect it first to connect a different account. | The key belongs to another Klaviyo account. Disconnect, then connect with the new key. | | The Klaviyo connection changed while this was saving. Refresh the page and try again. | Two changes were made at the same time. Refresh the page and try again. | | Can't reach Klaviyo balance sync right now. Retrying… | The card could not reach the sync service. It retries on its own. A connect that timed out may still have succeeded, so check the status before trying again. | | Klaviyo balance sync isn't available yet. Contact Shopwaive support. | The sync is not switched on for this admin. Contact support. | | Klaviyo balance sync can't be shown right now. Reload the page to try again. | The card ran into an error. Reload the page. | | Removing Shopwaive balances from your Klaviyo profiles. You can disconnect when this finishes. | You clicked Connect or Disconnect while a removal was running (the card may add "N profiles left"). Wait for the badge to change from **Removing balances**, then disconnect. | Other things to check: * **`shopwaive_balance` is not in the segment builder.** It appears once at least one profile carries it. Wait until the card shows at least one balance update sent. * **A value in Klaviyo differs from Shopwaive.** Wait a minute for a recent change to arrive. A difference that lasts longer is repaired by the daily check (after midnight UTC). If it persists after that, contact support. * **An email shows an old balance.** Add a Time Delay of at least 10 minutes before the email, as described above. Questions? Send us a message in the in-app chat or email .