Migrating your Klaviyo flows to the new Giftnote integration
How to tell if you are on the original Giftnote Klaviyo integration, how the old events and merge fields map to the new ones, and the order to run the cutover in.
Written By Giftnote Team
Last updated 1 day ago
If your Klaviyo flows were set up more than a year ago, you are probably on our original integration. It still sends events, so nothing looks broken. But the event names and merge fields changed, and the old version cannot reach most of what Klaviyo can now do with your gift data.
This guide covers what changed, how the old events map to the new ones, and the order to do the cutover in so your customers never get two emails or none.
Am I on the old integration?
Open Klaviyo and look at your Giftnote metrics. You are on the old integration if you see metric names that start with Giftnote -, such as Giftnote - Order Message or Giftnote - Voucher Delivered.
The new integration uses plain names with no prefix: Placed Gift Order, Received Gift Order, Gift Card Delivered, and so on.
Two other signs:
- Your gift emails all run from one or two combined flows rather than a separate flow per event.
- Your templates use fields like
{{ event.gift_to }}and{{ event.voucher_code }}.
What you get by migrating
- A flow per event instead of one combined flow. You can write a different email for a scheduled gift, a delivered gift, and a gift card, rather than branching inside one flow.
- Gift card events that most old setups never had. Redeemed Gift Card and Issued Store Credit did not exist in the original integration. Neither did the balance data behind reminder campaigns.
- More data in the payload. Gift card SKU, expiry date, and delivery method, so you can build conditional templates.
- Multi Gift events for corporate orders, if you use the Multi Gift portal.
- Segments that actually work. The segments in Klaviyo + Giftnote segments are built on the new event names.
How the old events map to the new ones
Use this to work out which new flow replaces which old one. Confirm the names against your own account before you build — send a test event from Giftnote and check the Klaviyo activity feed.
How the merge fields change
This is the part that silently breaks templates. Old field names do not error, they just render empty.
Two rules worth knowing before you rewrite anything:
- Multi-word field names need the lookup filter. Dot access cannot reach a key with a space in it, so
{{ event.Gift Card Code }}will never work. - Always chain
|default:''. Without it, an event that has no value for that field renders the literal wordNonein your customer's email.
Product and gift card blocks
Dynamic tables for products and gift cards work the same way as before: a row collection, a row alias, and section display logic so empty tables do not appear. Check the field names against a test event in your own account before you rebuild these blocks, as the block-level fields are the most likely to have moved.
The migration steps
The order matters. Steps 6 and 7 are the only ones with real risk — get them the wrong way round and customers get duplicate emails or none at all.
- Write down what is live today. List every Giftnote flow that is currently sending and which metric triggers it. You will switch these off later, and you need the list to be sure you replaced each one.
- Reconnect the integration. In your Shopify admin, open Giftnote, then Settings > Integrations > Klaviyo > Configure. Reconnect and approve the permissions. The integration comes back disabled. Leave it that way for now.
- Send test events. Use the Test buttons in the Giftnote integration settings, then check Klaviyo's activity feed to confirm the new events are arriving and to see the real payload.
- Build your new flows. One flow per event, using the tables above. If you would rather not start from scratch, ask us for our prebuilt flow templates. We can send you the structure to build from, or copy them straight into your account if you invite us.
- Update the merge fields and brand the templates. Use the field table above. This is where most of the elapsed time goes, because it is design work.
- Apply transactional status to every new flow. Gift recipients have not opted in to marketing, so without transactional status Klaviyo will accept the event and send nothing. This is the most common reason a new setup appears to fail.
- Switch the old flows off at the same time you turn the new ones on. Both sets live means every customer gets two emails.
- Turn off the matching Giftnote notifications. In Giftnote, go to Settings > Notifications, open each email that Klaviyo now handles, and toggle Email enabled off. Save.
- Enable Klaviyo in Giftnote and save. Events now flow to your live templates.
- Place real test orders. One per scenario: send now, send later, on delivery, gift card purchase, and a gift card redemption. Check what actually lands in the inbox, not just what Klaviyo reports.
- Clean up the old metrics. Klaviyo accounts have a metric limit and old Giftnote metrics still count against it. Some long-running accounts carry more than twenty.
Things that catch people out
Your historical data does not come across. Klaviyo only receives events from the reconnection date onward. If you want a gift card reminder campaign to include people who bought before you migrated, that first send needs a manual export. Everything after migration is automatic.
Suppressed contacts still will not receive anything. Suppression overrides transactional status. If a recipient's address bounced or unsubscribed previously, their gift email is blocked no matter how the flow is configured.
Gift card events may never have been set up at all. On plenty of old accounts, only the gift message flows were built. Check whether your gift card emails are coming from Klaviyo or still from Giftnote's own templates before you assume you are replacing something.