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 — the first name in the vocative case (Jane)
   • Czech last name — the last name in the vocative case (Nováku)
   • Gender — male, female, or unknown

Caution

These three are the only properties the app writes. There is no property holding a complete greeting — Czech addressing is the first name on its own. Compose the full form of address in your template from Czech addressing and Czech last name.

Caution

If the app cannot decline a customer’s first name, it writes none of these properties — not even Gender. The same is true for customers who have not been processed yet. Every template therefore needs a sensible variant with no name in it.

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.

Note

Klaviyo templates use Django syntax, not Liquid. The conditional tags are {% if %} / {% elif %} / {% else %} / {% endif %}; Liquid’s {% elsif %} does not work in Klaviyo.

Display the declined first name

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

Greeting with fallback

Danger

Never fall back to person.first_name. That variable holds the name in the nominative case, so it produces “Dobrý den, Lenka” instead of the correct “Dobrý den, Lenko”. The fallback fires precisely for the customers whose names the app could not decline, and for them no correct vocative form exists at all. The only safe fallback is a greeting with no name.

{% if person|lookup:'Czech addressing' %}
  Dobrý den, {{ person|lookup:'Czech addressing' }},
{% else %}
  Dobrý den,
{% endif %}

Gender-conditional greeting

In Czech, “Vážený pane” and “Vážená paní” are followed by the last name, so use Czech last name there. The first name (Czech addressing) belongs in the informal greeting.

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

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 also skipped for every customer whose first name the app cannot decline — those customers never reach the Klaviyo step, so none of the three properties appear on their profile. See Troubleshooting for which names the app accepts.

Otherwise, 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

Wrap the greeting in a condition so the no-name variant is used when the property is absent:

{% if person|lookup:'Czech addressing' %}Dobrý den, {{ person|lookup:'Czech addressing' }},{% else %}Dobrý den,{% endif %}

Do not close the gap with |default:person.first_name — that inserts the nominative form of the name into a slot that requires the vocative.