Klaviyo events
Send each balance moment to Klaviyo as a Shopwaive metric: connect with your one Klaviyo key, build a flow on a metric, and see when each metric fires and which properties it carries
Klaviyo events send each balance moment to Klaviyo as a Shopwaive metric: a customer earning a balance, redeeming it, getting it back, losing it when it expires, or pressing Redeem. A Klaviyo flow can start each time the moment happens, and its message can show that moment's values, such as the amount.
In Shopwaive the feature is the Klaviyo balance events card, under Settings > Integrations, below the balance sync card.
Balance events and Klaviyo balance sync use one Klaviyo key and do different jobs:
Balance sync keeps one number on each profile,
shopwaive_balance: the customer's balance now. Use it in segments, and to show the balance in a message.Balance events send one event for each moment, with that moment's own values. Use them to start a flow when the moment happens.
An event never writes a profile property, and no event property has a name that starts with shopwaive_.
The Klaviyo key
Balance events and balance sync use the same Klaviyo private API key. Create it once, with these four permission scopes, and use it for both. Klaviyo's form names the access levels No Access, Read Access and Full Access.
Accounts
Read Access
Balance sync and balance events read the name of your Klaviyo account.
Events
Full Access
Balance events create the events. Read Access is not enough: Full Access is the only level that lets a key create events.
Metrics
Read Access
Balance events read your account's metrics once, to check the key.
Profiles
Full Access
Balance sync writes shopwaive_balance. Balance events only read profiles, to check that the key belongs to the Klaviyo account that balance sync writes to.
Leave every other scope at No Access. The steps to create the key are in Step 1 of the balance sync page.
Klaviyo shows a key only once, and does not let you add a scope to a key that exists: see Klaviyo's How to create or clone a private API key.
If your balance sync key was created with only Accounts and Profiles, create a new key with all four scopes and save it in balance sync (Replace key, then Save new key): balance events connect with it too. You can then delete the old key in Klaviyo.
If your balance sync key has the four scopes and you no longer have it, create one new key with all four scopes and save it in balance sync (Replace key, then Save new key): balance events take it too.
To replace your key, save the new one in balance sync: balance events take it too.
Connect events
In your Shopify admin, open Shopwaive, then Settings > Integrations.
Connect balance sync with your one Klaviyo key, made with the four scopes above. Balance events connect with the same key at the same time.
Under Events sent to Klaviyo, tick the moments you want to send.

On a Balance store, type your three-letter currency code, such as USD, under Currency and click Save currency.
Shopwaive checks the key with Klaviyo. The card then reads "Connected to" followed by your Klaviyo account name, and shows the checkboxes described under Which events are sent. Paste the key into Shopwaive yourself. Do not email it to support.
The email address for test events is optional:
With an address, connecting also sends one test
Shopwaive: Balance Earnedevent to it, so that metric appears in Klaviyo within a few minutes. Use a real address that you can check. A test event never starts a flow.Without an address, Shopwaive checks the key without creating any event, profile or metric in your Klaviyo account.
Either way, each metric appears in Klaviyo under Analytics > Metrics with its first event. To see every metric that is switched on without waiting for real events, type an address and click Send test events: see Test events and real events.
If the card answers "This key can't read metrics" or "This key can't create events", the key is missing a scope. Create a new key with all four scopes and paste that one.
Build a flow from a Shopwaive metric
A Shopwaive metric starts a flow each time its event arrives, and the flow's messages can show the event's own values. The example below thanks a customer for the points they have just earned.
Make sure Klaviyo lists
Shopwaive: Balance Earned. A metric appears with its first event, or within a few minutes of clicking Send test events in the card.In Klaviyo, open Flows, click Create flow, and choose Build your own. Choose the trigger Metric and pick
Shopwaive: Balance Earned.Add a trigger filter on
note, so that only the deposits you mean start the flow. If your earn deposits carry notes such asEarned 12.5 Points, usenotecontainsEarned. Type the words exactly as your notes write them. The filter needs Include the deposit note, which is ticked after you connect.In the trigger settings, leave Re-entry criteria at Allow re-entry, Klaviyo's default for a metric trigger. The customer then gets the email each time they earn.
Add an email to the flow, and show the event's values in it with
{{ event.amount }}and{{ event.balance_after }}, as in the example below.Keep the email in Draft. Check it in Preview & test against a real event, then set it to Live.


In the example, the email's subject line and preview text carry the two tags:

No Time Delay is needed here. Both values come from the event itself, and
{{ event.balance_after }}is the balance just after this deposit. A message that shows{{ person.shopwaive_balance }}instead needs a Time Delay: see When events arrive.A test event shows placeholders, 0 for every number and
testfor text. Check the email against a real event before you set it to Live.On a Balance store, write the amounts as money, for example
${{ event.amount }}.Smart Sending can skip an email when the customer was emailed recently. Decide per email whether to keep it on: see Smart Sending.
Klaviyo's own pages: How to create a metric-triggered flow, Understanding flow triggers and filters and How to use event data to personalize email and SMS flows.
Flows for other moments
they earn points
Metric: Shopwaive: Balance Earned
A trigger filter on note, as in the example above.
a welcome deposit lands
Metric: Shopwaive: Balance Earned
The trigger filter note equals the note of your welcome deposit, and Re-entry criteria set to No re-entry.
they redeem their balance
Metric: Shopwaive: Balance Redeemed
No filter is needed. {{ event.amount }} is the amount used, and {{ event.balance_after }} what is left.
a redeemed balance is given back
Metric: Shopwaive: Balance Refunded
No filter is needed.
Klaviyo cannot change the trigger of a flow that exists. To move a flow that is triggered by a list or a segment onto a Shopwaive metric, save its emails as templates, then build a new flow on the metric and add the saved templates: see Klaviyo's How to change a flow trigger.
The seven metrics
Shopwaive: Customer clicked Redeem
Redeem was pressed and Shopwaive created the discount or gift card for it. No balance has moved yet.
On
Shopwaive: Balance Earned
A deposit reached the customer's wallet.
On
Shopwaive: Balance Redeemed
A paid order used the customer's balance.
On
Shopwaive: Balance Refunded
A balance that the customer had redeemed was given back.
On
Shopwaive: Balance Expired
Points or a balance expired.
On where Shopwaive has switched it on for your store, otherwise off. See Balance Expired.
Shopwaive: Balance Adjusted
A balance was set to a new value, or lowered, outside a redemption or an expiry.
Off. You switch it on in the card.
Shopwaive: Balance Imported
A bulk import, added by Shopwaive support as history.
No checkbox. It never starts a flow.
Shopwaive sends each name exactly as it is written here and never renames it. In Klaviyo, a metric is listed under Analytics > Metrics, with the source API, once an event for it has arrived.
Properties that the metrics share
store
Text
your-store
Your store's handle: the part of your myshopify.com address before .myshopify.com.
unit
Text
points
points on a Loyalty and Rewards store, money on a Balance store.
points_multiplier
Number
1
Your Multiplier for display when it is above 1, otherwise 1.
currency
Text
USD
The three-letter currency code, on a Balance store, when Shopwaive knows it. Never sent on a Loyalty and Rewards store.
shopify_customer_id
Text
1234567890123
The customer's Shopify id, when Shopwaive holds it.
store is on all seven metrics. The other four are on every metric except Customer clicked Redeem.
How values are sent:
Numbers are plain numbers in the units your store shows, by the same rule as
shopwaive_balance. On a Loyalty and Rewards store they are whole points, multiplied by your Multiplier for display when it is above 1. On a Balance store they are money to two decimals. A number is sent as a number, so 55.30 arrives as 55.3.Points are rounded. A deposit of 12.5 points arrives with
amount13, while its note shows 12.5. A movement that is too small to show, such as 0.4 points, arrives withamount0, and the event is still sent.Amounts are always positive. The metric says which way the balance moved.
Timestamps are in UTC, in the form
2026-01-15T09:30:00Z. Format a timestamp in your template before you show it to a customer.True or false values arrive as true or false, never as text.
A value that Shopwaive does not know is left out. It is never sent empty.
In a flow triggered by the metric, show a property with a tag such as {{ event.amount }}. Tags are case-sensitive. Klaviyo's Preview & test shows the properties of recent events, and you can copy each tag from it.
Events also carry values that Shopwaive keeps for its own records. They are not in the tables below, and you can ignore them: lane, kind, source, mode, entry_key, ledger_seq, amount_minor, balance_before_minor, balance_after_minor, order_source, code_amount, code_currency, multiplier_applied, requested, applied, shortfall, gift_card_id, action_run_id, line_item_id, lot_id, deposited_at, expiry_rule, refund_id, refund_of, restorations, refund_basis, import_id, row and replayed.
Shopwaive: Customer clicked Redeem
It fires when a customer presses Redeem at checkout or in their account, or staff press it at the point of sale, and Shopwaive creates the discount or gift card for it. No balance has moved yet.
rail
Text
discount
How the customer is redeeming: discount for a discount code, gift for a gift card, gift_b2b for a B2B gift card.
pre_credit
Number
100
The customer's balance just before Redeem was pressed, when Shopwaive knows it.
code_id
Text
1461234567002
The id of the discount or gift card that was created. It is never the code itself.
store
Text
your-store
Your store's handle.
It fires for each press that creates a discount or gift card, whether or not the order is completed.
When the same customer presses Redeem again within 60 seconds, for the same way of redeeming, no second event is sent.
A customer who creates a gift card from their account page sends this event too.
It does not carry: an amount, the code itself, an order (none exists yet), where Redeem was pressed, or unit, points_multiplier, currency and shopify_customer_id.
Shopwaive: Balance Earned
It fires when a deposit reaches a customer's wallet, for example from Shopify Flow's Increment balance action, the Shopwaive API, a refund to the balance at the point of sale, a budget, or a product purchase that is set up to add a balance.
amount
Number
13
The amount that was added.
balance_before
Number
25
The balance before the deposit.
balance_after
Number
38
The balance after the deposit.
note
Text
Earned 12.5 Points
The note that was written with the deposit.
first_deposit
True or false
false
True when the wallet had no earlier deposit, redemption, refund, expiry or adjustment, false when it had. Bulk imports and deposits to a whole segment do not count.
earn_source
Text
shopify_flow
shopify_flow for a deposit made by a Shopify Flow action, product_flow for a product purchase that adds a balance, api for any other deposit.
expires
True or false
true
Whether the deposit expires.
expires_at
Timestamp
2027-01-15T00:00:00Z
When the deposit expires. Sent only when expires is true.
order_id
Text
5001234567890
The id of the Shopify order that the deposit names, when it names one.
first_depositdoes not mean one particular welcome deposit. To greet customers when a welcome deposit lands, filter on that deposit'snote.first_depositignores imported balances. On a store whose customers were imported, the first deposit after the import counts as a first deposit.first_depositis left out when Shopwaive cannot tell. Such an event does not match a filter on it.A deposit from a product purchase carries no
amount,balance_beforeorbalance_after.
It does not carry: a tier or a reward name, or where the deposit was made. A bulk import and a deposit to a whole customer segment are never sent. See What never sends an event.
Shopwaive: Balance Redeemed
It fires when a paid order uses the customer's balance, by discount code, gift card, B2B, point of sale or draft order. It fires when Shopify reports the order as paid, which can be a few minutes after checkout.
amount
Number
200
The amount of balance that the order used.
balance_before
Number
659
The balance before the order.
balance_after
Number
459
The balance after the order.
order_id
Text
5001234567890
The id of the Shopify order.
order_name
Text
1001
The order's number, with no # in front.
rail
Text
discount
How the balance was redeemed: discount for a discount code, gift for a gift card, gift_b2b for a B2B gift card.
It does not carry: a note, the code of the discount or gift card, the items or the total of the order, or a value for Klaviyo's revenue reporting.
Shopwaive: Balance Refunded
It fires when Shopify Flow's Refund balance action gives back a balance that the customer had redeemed.
amount
Number
200
The amount that was given back.
balance_before
Number
459
The balance before the refund.
balance_after
Number
659
The balance after the refund.
note
Text
Refunded (credited) 200 points redeemed on Order 1001
The note that Shopwaive wrote for the refund.
order_id
Text
5001234567890
The id of the Shopify order whose redemption was given back.
rail
Text
discount
How the balance had been redeemed, when Shopwaive recorded it: discount, gift or gift_b2b.
It does not carry: the refund of the order itself. That is a Shopify moment. When an order is refunded in full, Klaviyo's Shopify integration sends it as its own metric, Refunded Order. Klaviyo does not receive that event for a partial refund: see Klaviyo's Shopify data reference. A refund to the balance made at the point of sale is Balance Earned, and a balance that staff set to make up for a refund is Balance Adjusted.
Shopwaive: Balance Expired
It fires when points or a balance expire in Shopwaive.
On a store where each deposit has its own expiry date, one event is sent for each deposit that expires. A customer whose three deposits expire together gets three events.
On a store that expires each customer's whole balance on a single date, one event is sent for the whole balance.
Balance Expired is switched on per store by Shopwaive, for stores that use Shopwaive's balance expiry engine. Where it is switched on, it is on from the moment you connect and its checkbox in the card is ticked. If your store expires balances and the checkbox is not ticked, contact Shopwaive support.
To remind customers before their points expire, use the Klaviyo expiry properties instead. This metric fires after the points are gone.
Before you build on Balance Expired
It starts when it is on. Expiries recorded before Balance Expired was on are not sent. One exception: an expiry recorded in the six hours before can still arrive.
One event for each expired deposit. A metric-triggered flow starts for every event, so a customer whose deposits expire together would get one message for each deposit. Limit how often one customer can enter the flow. See Build a flow on Balance Expired.
The amount belongs to one event. Where each deposit has its own expiry date,
amountis one deposit's amount. It is not the total that the customer lost that day.Expiry comes in bursts. Many customers' points can expire in the same hour, and every event counts towards your store's two daily caps. If one day brings more events than a cap allows, the events past the cap are not sent as they happen, and no flow starts for them. On a store that expires each customer's whole balance on a single date, one expiry can reach every customer at once, and the card says so under the checkbox.
Test events are optional. To see the metric and its properties in Klaviyo before the first real expiry, click Send test events in the card while the checkbox is ticked.
Keep the flow in Draft until a real event has arrived and you have checked it in Preview & test.
Properties of Balance Expired
amount
Number
20
The points or balance that expired with this event: one deposit's amount, or the whole balance on a store that expires the whole balance on a single date.
balance_before
Number
659
The balance before this expiry.
balance_after
Number
639
The balance after this expiry.
expired_at
Timestamp
2026-10-15T00:13:08Z
When Shopwaive recorded the expiry.
note
Text
19.97 Points expired
The note that Shopwaive wrote for the expiry.
reference
Text
6118420000001
The id of the deposit that expired. You can ignore it. It is not sent when a whole balance expired.
amount,balance_beforeandbalance_afterare on the event when Shopwaive recorded them with the expiry. An event without them still carriesexpired_atandnote. Before you show one of them in a message, check a real event from your store in Preview & test.amountis rounded the way your store shows a balance, and the note is not. In the example above, 19.97 points expired,amountis 20, and the note reads 19.97. Show the amount or the note in one message, not both.When several deposits expire together, each event carries its own
balance_beforeandbalance_after. Only the last one carries the balance that the customer ends with.
It does not carry: the date on which the points were due to expire, the total that the customer lost that day, or the note of the deposit that expired.
Build a flow on Balance Expired
In Klaviyo, open Flows, click Create flow, and choose Build your own. Choose the trigger Metric and pick
Shopwaive: Balance Expired. Klaviyo lists the metric once its first event has arrived, or once you click Send test events in the card.If your store's events carry
amount, add the trigger filteramountis at least 1. It keeps out an expiry that is too small to show, whoseamountis 0.In the trigger settings, set Re-entry criteria to Allow re-entry after a time period, for example 1 day. A customer whose deposits expire together then gets one message.
Add a Time Delay of at least 10 minutes before the message. Balance sync and balance events are separate, so an event can reach Klaviyo before the new
shopwaive_balancedoes. When many balances change at once, balance sync needs longer: see Timing.Write the message. To show the balance the customer has now, use
{{ person.shopwaive_balance }}, which needs balance sync to be connected.Keep the message in Draft until a real event has arrived. Check it in Preview & test, then set the message to Live.
A message that works on every store:
If your store's events carry the amount:
With a re-entry limit, the message is sent for the first event of that period, and {{ event.amount }} is that one deposit's amount. On a Balance store, write the amounts as money.
Klaviyo describes Re-entry criteria in How to create a segment- or list-triggered flow, and says there that it manages re-entry the same way for every flow type. That page also says the setting is still reaching some accounts. Klaviyo's steps for the trigger are in How to create a metric-triggered flow.
Shopwaive: Balance Adjusted
It fires when a balance is set to a new value, or lowered, outside a redemption or an expiry:
a balance is set to a new value, by staff in Shopwaive, by Shopify Flow's Set balance action or through the API;
a deposit is voided, for example by Shopify Flow's Void deposits action;
a decrease is sent through Shopify Flow's Increment balance action with a negative amount, through the API, or removed at the point of sale;
a product purchase lowers or resets a balance.
This metric is off until you tick its checkbox in the card. It is off by default because a correction made by your staff would become a lasting record on the customer's profile in Klaviyo.
amount
Number
60
The size of the change.
balance_before
Number
100
The balance before the change.
balance_after
Number
40
The balance after the change.
direction
Text
down
up when a set raised the balance. down or void when the balance was lowered.
set_target
Number
40
The balance that a set aimed for, or the balance that a product purchase left.
adjust_source
Text
api
Shopwaive's label for how the change was made: admin, api, shopify_flow, void or product_flow. A set that raised the balance reads admin. A decrease reads shopify_flow when a Shopify Flow action made it, and api otherwise.
note
Text
Balance corrected by support
The note that was written with the change.
order_id
Text
5001234567890
The id of the order that the change names, when it names one.
A voided deposit arrives as a decrease, with the
directiondownorvoid.A change made by a product purchase carries no
amount,balance_beforeorbalance_after.
It does not carry: the name of the staff member who made the change.
Shopwaive: Balance Imported
A bulk import of balances never sends an event while it runs. Shopwaive support can add an import to Klaviyo afterwards, as history under this metric. It never starts a flow, and it has no checkbox in the card and no test event. It has no properties to build on.
Test events and real events
Test events are optional. In the connected card, Send test events sends one test event for each metric that is switched on, to the address in Email address for test events. The card says: "Optional: send one test event for each metric that is turned on, so every metric and its properties can be picked in Klaviyo before the first real event arrives. Test events can't trigger a flow."
The property test
true
Not sent
Which properties
Every property name that the metric can carry, with the ones you can ignore
Only the values that Shopwaive knows for that moment
The values
Placeholders: 0 for a number, false for true or false, test for text, the time of the click for a timestamp. store is your real store handle.
The real values
Flows
Never starts a flow. It is marked as a test and sent as history.
Starts the flows that the metric triggers
So a property that you can pick in Klaviyo is not always on a real event. Build on the properties in the tables above, and check a real event in Preview & test before you set a message to Live.
Which events are sent
After you connect, the card shows a checkbox for each metric and for each setting.
Under Events sent to Klaviyo there is one checkbox for each metric except Balance Imported.
Shopwaive: Customer clicked Redeem, Shopwaive: Balance Earned, Shopwaive: Balance Redeemed and Shopwaive: Balance Refunded
Ticked
You
Shopwaive: Balance Adjusted
Not ticked
You
Shopwaive: Balance Expired
Ticked where Shopwaive has switched it on for your store, otherwise not ticked. It cannot be changed in the card.
Shopwaive support
Under What each event carries there are two more checkboxes. Both are ticked after you connect.
Include the deposit note sends
note. The card says: "The note is sent to Klaviyo as it is written, with email addresses removed from it." A note longer than 512 characters is cut and ends with "…".Include order identifiers sends
order_id,order_nameandshopify_customer_id. It also covers four of the values you can ignore:refund_id,line_item_id,action_run_idandlot_id.The card says of both: "An event that has been sent can't be changed or taken back from here, so turning this off only affects events sent from now on."
On a Balance store the card also shows Currency with the button Save currency: "The three-letter currency code sent with each event, such as USD." Shopwaive uses it when the balance change itself names no currency.
Daily caps
Each store has two daily limits, which the card calls caps. One limits how many events are sent to Klaviyo in a day. The other limits how many events are queued in a day, which means taken in by Shopwaive to be sent. A day runs from midnight to midnight UTC. Both caps are 5,000 unless Shopwaive support set other numbers for your store.
The card shows both numbers, with today's counts, in a line that starts "Daily caps (UTC day):". When your store reaches a cap, events stop until Shopwaive support releases it. Balance changes made after the cap was reached are not sent as they happen. Shopwaive support can add them to Klaviyo afterwards as history, which never starts a flow.
When events arrive
Usually within about a minute of the change. Shopwaive reads balance changes once a minute and sends them in order. Klaviyo then processes each event, and can take a few minutes to show it.
Each event carries the time of the change itself, not the time it was sent.
Balance Redeemed follows Shopify reporting the order as paid, which can be a few minutes after checkout.
A late event is history. An event that is sent more than five and a half hours after the change is recorded as history and does not start a flow.
The balance can arrive after the event. Before a message that shows
{{ person.shopwaive_balance }}, add a Time Delay of at least 10 minutes.
What never sends an event
A bulk import of balances, and a bulk deposit that Shopwaive runs on a schedule.
A deposit made to a whole customer segment at once.
Records that do not move a balance, such as a balance email, or a customer's Shopwaive account that is created without a deposit.
A customer's Shopwaive account that is deleted. No event is sent for the balance that goes with it.
A change whose amount is exactly 0. A change that is only too small to show is sent, with
amount0.Repairs that Shopwaive makes to its data.
Anything balance sync does.
A metric that is switched off.
A customer whose email address in Shopwaive is not a usable address.
Moments that happen in Shopify: orders, order refunds, fulfillment, new or updated customers, tags, discounts and gift cards that are created, and Shopify's native store credit.
Reward thresholds. Shopwaive sends no event when a balance crosses a threshold. For a threshold, use a segment on
shopwaive_balance.
Customer data in events
An event names the customer by email address only, so that Klaviyo can find the profile. Apart from the note, no property holds the customer's name, an address, the items of an order, or the code of a discount or gift card.
The note is the one piece of free text. Email addresses in a note are replaced by
[email removed]before it is sent. Any other personal detail in a note is sent as it is written, so keep personal details out of deposit notes, or untick Include the deposit note.An event for an address that has no profile in Klaviyo creates the profile. Klaviyo counts profiles towards your plan, as described under Before you start.
Shopwaive cannot change or delete an event once it is sent.
Questions? Send us a message in the in-app chat or email support@shopwaive.com.
Last updated