Skip to main content
Klaviyo

7. 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 you set up your Giftnote flows in Klaviyo more than a year ago, you're probably on our original integration. It still sends events, so nothing looks broken. The new integration uses different event names and merge fields and sends more gift data, so you need to rebuild your flows to use it.

Giftnote walks you through the switch on its Klaviyo settings page, and your current flows keep working until the very last step.

Settings β†’ Integrations β†’ Klaviyo, showing the connection and Integration Enabled switch.

Below you'll find how to check which one you're on, how the old events and fields map to the new ones, and the steps to switch over without customers getting 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.

Other signs:

  • In Giftnote, the Klaviyo settings page shows a Migrate to OAuth section marked Migration needed.
  • 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. Issued Store Credit did not exist in the original integration, and few accounts ever had a redemption event. 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.
  • Ready-made segments. 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. Before you build, send a test event from Giftnote and check the names in your Klaviyo activity feed.

Old eventNew eventSent to
Giftnote - Order Scheduled
Giftnote - Order Tracked
Placed Gift OrderCustomer
Giftnote - Order DeliveredGift Order DeliveredCustomer
Giftnote - Order MessageReceived Gift OrderRecipient
Giftnote - Voucher ScheduledPurchased Gift CardCustomer
Giftnote - Voucher DeliveredGift Card DeliveredCustomer
Giftnote - Voucher MessageReceived Gift CardRecipient
Giftnote - VoucherGift CardEither
Giftnote - Voucher Usage (some accounts only)Redeemed Gift CardEither
No equivalentIssued Store CreditEither
No equivalentThe Multi Gift events (see 2. Klaviyo Giftnote Events)Customer, recipient or your team

How the merge fields change

Old field names don't cause an error. They show up blank in the email, so check every template.

What it isOld fieldNew field
Recipient name{{ event.gift_to }}{{ event.To|default:'' }}
Sender name{{ event.gift_from }}{{ event.From|default:'' }}
Gift message{{ event.gift_message }}{{ event.Message|default:'' }}
Scheduled send time{{ event.time }}{{ event|lookup:'Scheduled Time'|default:'' }}
Gift card code{{ event.voucher_code }}{{ event|lookup:'Gift Card Code'|default:'' }}
Gift card value{{ event.voucher_value }}{{ event|lookup:'Gift Card Value'|default:'' }}
Delivery methodNot available{{ event|lookup:'Delivery Method'|default:'' }}
Gift card expiryNot available{{ event|lookup:'Gift Card Expiry'|default:'' }}
Gift card SKUNot available{{ event|lookup:'Gift Card Sku'|default:'' }}

Two rules before you rewrite anything:

  • Multi-word field names need |lookup:. 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 word None in 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. The fields inside these blocks are the most likely to have changed.

The migration steps

Do these in order. Your old flows keep sending the whole way through, until you complete the migration in step 11. The risky moment is step 9: get it wrong and customers get duplicate emails or none at all.

  1. 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.
  2. Open the migration. In your Shopify admin, open Giftnote and go to Settings β†’ Integrations. Select Manage settings on Klaviyo, then open Migrate to OAuth. It shows three steps and how many are done.
  3. Connect via OAuth. Select Connect via OAuth, sign in to Klaviyo and approve Giftnote’s access. Your old private-key connection keeps working until you finish, and Giftnote keeps sending the old event names, so your current flows carry on exactly as before. Each event keeps the on/off setting it had.
  4. Start sending the new event names. Select Start sending new events. From now on Giftnote sends each event to Klaviyo twice: once under its old name and once under its new name. Your old flows keep working. Keep every new flow in Draft until step 9. While both names are being sent, a live flow on a new name sends its email too, so a customer would get the old email and the new one.
  5. Send test events. On the same page, select Send all test events, then check Klaviyo’s activity feed to confirm the new events are arriving and to see the real payload.
  6. Build your new flows. One flow per event, using the tables above. To skip starting from scratch, email support@giftnote.com and we'll add our ready-made flows to your Klaviyo account as drafts. See 4. Ready-made Klaviyo flows from Giftnote.
  7. Update the merge fields and brand the templates. Use the field table above. This design work takes the longest.
  8. 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. Remove any sign-up block or shop button first, because Klaviyo won't approve an email that has one, and turn Smart Sending off on gift emails.
  9. Switch over in one go. Set each new flow to Live and switch its old flow off at the same time. Both live means every customer gets two emails.
  10. Check Giftnote isn’t also sending. In Giftnote, go to Settings β†’ Notifications. For each notification Klaviyo now handles, make sure the Email switch on its row is off, then save.
  11. Complete the migration. Back on the Klaviyo settings page, select Complete migration and confirm. Giftnote removes your old private API key and from then on sends only the new event names. Do this only once your new flows are live, because your old flows stop receiving events at this point.
  12. 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.
  13. 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.

Connecting again never pauses events. When you connect with OAuth from the migration, Giftnote starts sending again straight away. To pause everything without disconnecting, turn off Send events to Klaviyo on the Klaviyo settings page. Each notification keeps its own setting.

Things that catch people out

The new event names start with no history. Klaviyo only has data under a new name from the day you start sending it (step 4). Your old metrics keep their history. If you want a gift card reminder campaign to include people who bought before you migrated, email us for an export for that first send. Everything after that 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.