Klaviyo Integration

The CZ Names Klaviyo integration automatically syncs the declined name forms and gender to matching Klaviyo profiles. Once synced, you can use the Czech addressing data in any Klaviyo email, SMS, or flow template.

Setup

You need two Klaviyo API keys: a Public key (also called Site ID) and a Private key.

Finding your Klaviyo API keys

1. Log in to your Klaviyo account
2. Go to Account → Settings → API Keys
3. Copy your Public API Key (visible on the main API Keys page)
4. Create a new Private API Key with at least profiles:read and profiles:write scopes, then copy it

Entering keys in the app

1. Open the CZ Names app in your Shopify admin
2. Go to Settings → Klaviyo Integration
3. Paste your Public API Key and Private API Key
4. Click Save

The integration activates immediately for all subsequent customer creates and updates.

How the sync works

When a customer’s name is processed:

1. The app declines the name and writes the Shopify metafields
2. The app then looks up the customer’s email address in Klaviyo to find their profile
3. If found, the app updates the Klaviyo profile with three custom properties:
   • Czech addressing — declined first name
   • Czech last name — declined last name
   • Gender — male, female, or unknown

Caution

There is a 3–5 minute delay between a new customer being created in Shopify and their profile becoming available in Klaviyo. During this window, the sync will be skipped. The Klaviyo sync does not retry automatically — it runs once per customer event.

If you have customers who signed up before the integration was enabled, trigger a re-sync by making a small edit to their Shopify customer profile (for example, re-saving their name). This fires a customer update webhook, which triggers both the declension and the Klaviyo sync.

Using Czech addressing in Klaviyo templates

Once the properties are synced to a Klaviyo profile, you can use them in any Klaviyo email or SMS template with the person|lookup filter.

Display declined first name

{% if person|lookup:'Czech addressing' %}
  {{ person|lookup:'Czech addressing'|default:'' }}
{% endif %}

Full greeting with fallback

{% if person|lookup:'Czech addressing' %}
  Vážený zákazníku {{ person|lookup:'Czech addressing' }} {{ person|lookup:'Czech last name' }},
{% else %}
  Vážený zákazníku {{ person.first_name }},
{% endif %}

Gender-conditional greeting

{% if person|lookup:'Gender' == 'male' %}
  Vážený pane {{ person|lookup:'Czech addressing' }},
{% elif person|lookup:'Gender' == 'female' %}
  Vážená paní {{ person|lookup:'Czech addressing' }},
{% else %}
  Dobrý den, {{ person|lookup:'Czech addressing'|default:person.first_name }},
{% endif %}

Tip

Always include a | default: person.first_name fallback for the case where the Czech data has not yet synced to Klaviyo. This prevents empty greetings in your emails.

Using in Klaviyo flows

The Czech profile properties can be used as flow filter conditions as well. For example:

• Trigger a flow only for customers where Gender equals female
• Personalize product recommendations with a gendered greeting

To access the properties in a flow condition, select Profile property → Czech addressing (or Czech last name / Gender for the other properties).

Troubleshooting Klaviyo sync

Properties not appearing on Klaviyo profiles

Cause 1 — Incorrect API keys: Verify the Private API Key has profiles:read and profiles:write permissions. Re-enter the keys in the app settings and save.

Cause 2 — New customer, timing issue: For customers created very recently, Klaviyo may not have created their profile yet. Wait 5 minutes and then make a small edit to the Shopify customer to trigger a re-sync.

Cause 3 — Email mismatch: The sync matches customers by email address. If the email on the Shopify customer record differs from the email on the Klaviyo profile, the profile will not be found and the sync will be skipped.

Sync skipped for a customer

A sync is skipped when the customer email doesn’t exist as a Klaviyo profile yet. This is expected for brand-new customers — re-triggering the webhook after 5 minutes will resolve it. If the issue persists, contact support at integrace@soundsgood.agency.

Template shows blank instead of the name

Ensure you have the fallback in place:

{{ person|lookup:'Czech addressing'|default:person.first_name }}

If the property is completely absent on the profile (not just empty), the |default: filter will catch it.