Klaviyo custom properties: a data governance guide

Short answer. Use Klaviyo custom properties for current, profile-level facts that change segmentation, flow logic, or personalization. Give every property a controlled name, type, source, allowed values, update rule, owner, and retention purpose. Use events for things that happened. A platform that permits many properties still needs a small governed data model.

Klaviyo custom properties can store preferences, sizes, loyalty states, quiz answers, account attributes, or calculated customer traits. They can come from forms, imports, ecommerce integrations, APIs, or middleware, then power segments, flow filters, and content.

Klaviyo's current custom property guide says custom properties can be collected through forms and preference pages or added manually and by CSV. The platform supports using them in segmentation, flow filtering, and dynamic content. This article was reviewed July 16, 2026.

Custom property or event?

Use a property for the current value of a profile-level fact. Use an event for an occurrence with a time and context.

Often both are useful: an event records the change and a property exposes current state. The source system should determine and update them consistently.

Do not replace rich event history with dozens of last_* properties unless a current-state segment or integration requires them.

Understand Klaviyo and custom properties

Klaviyo profiles include platform-managed properties such as email, name, phone, address, source, locale, time zone, and consent-related fields. Custom properties are created for brand-specific use.

Klaviyo's current profile property reference warns against naming a custom property the same as a Klaviyo property because segmentation may not work as intended. Keep a reserved-name list and naming review.

Some platform properties cannot be edited by CSV. Do not try to recreate or override system-managed lifecycle fields with similarly named custom values.

Consent deserves special treatment. A custom property such as sms_opt_in = true is not automatically the platform's channel consent state or sufficient evidence for sending. Use supported subscription and consent mechanisms, and retain source and timestamp according to applicable requirements.

Create a property dictionary

Use a shared data dictionary:

Add created date, deprecation state, and downstream dependencies. This turns a property from an interface label into an operational contract.

Use a naming standard

Choose one readable convention, often lowercase snake_case:

• preferred_size
• loyalty_tier
• subscription_status
• account_role
• favorite_categories
• last_modeled_value_at

Avoid spaces, inconsistent capitalization, vendor-specific prefixes without purpose, and names that hide meaning such as status2 or segment_A.

Name booleans so true is understandable: is_wholesale_customer, not wholesale. For timestamps, add _at; for dates without time, use a documented date convention. For calculated properties, identify the model and recency if stale values would mislead.

Never encode consent or sensitive categories in casual free text. Involve privacy and security owners when data is sensitive, regulated, or unnecessary for the use case.

Choose the right data type

Klaviyo segment operators depend on property type. A number stored as a string cannot reliably support numeric comparison. A date stored in inconsistent text cannot support time logic.

Common types:

• string for one controlled label;
• number for counts, scores, or monetary values;
• boolean for true or false states;
• date or datetime for time-based rules;
• list for multiple full values.

Normalize before sending. Do not mix VIP, Vip, vip, and gold if they mean the same tier. Do not mix false, 0, and empty.

Klaviyo's reference notes that contains applies to list data types and expects full list values, not arbitrary substring matching. Test segment operators with real examples.

Changing a type after production can create confusing historical values. Prefer a versioned replacement property, backfill controlled records, update dependencies, then deprecate the old field.

Choose the source of truth and update rule

Every property needs one authoritative source or an explicit precedence rule.

Examples:

• preference center wins for stated content preference;
• ecommerce platform wins for customer account status;
• subscription platform wins for subscription state;
• data warehouse wins for calculated CLV model;
• customer support may update a service preference through a governed action.

Avoid uncontrolled last-write-wins from forms, imports, apps, and APIs. A stale CSV should not overwrite a newer customer choice.

For each source, define full versus partial sync, update frequency, deletion behavior, retry, monitoring, and backfill. Decide whether null means unknown, clear the value, or do nothing.

Collect properties through forms and preferences

Forms can create custom properties from responses. Ask only for data that improves the experience. Each extra field adds friction and governance work.

Good candidates:

• product interest;
• size or fit preference;
• content topic;
• replenishment context;
• account role;
• preferred frequency;
• locale or store market.

Test exact stored values from every form variation. Klaviyo currently notes that repeated collection of the same property keeps the latest submitted value rather than a history of each response. Use an event or external survey system if each submission must be retained.

Preference pages should distinguish channel subscription from content and frequency preferences. If someone selects fewer newsletters, do not accidentally unsubscribe them from necessary operational messages or retain promotion after a global unsubscribe.

Import properties by CSV safely

Before import:

1. deduplicate by stable identity;
2. normalize headers and values;
3. choose data types;
4. remove columns with no target use;
5. separate active subscribers from suppressions;
6. sample and count the file;
7. document source and extraction date.

Do not check an option that subscribes imported profiles unless the file contains valid eligible subscribers and the action matches the intended consent state. Klaviyo's current property documentation specifically cautions imports to retain existing subscription status when the upload is only adding properties.

Test a small file first. Inspect profiles, segments, date parsing, booleans, lists, and non-ASCII characters before full import.

Send properties through API or middleware

Use least-privilege credentials, stable identity, retries, rate handling, and structured logs. Validate payload size and types. Do not log secrets or unnecessary personal data.

Create a contract test that sends representative values and verifies the resulting Klaviyo profile. Monitor missing required fields, unknown values, update latency, and volume changes.

If the integration updates both profile properties and events, define ordering. A flow triggered by an event may evaluate profile state before a delayed property update arrives. Include needed event context in the event payload or sequence updates safely.

Use properties in segmentation

Build a segment only when it changes treatment. Examples:

• preferred_category = skincare and email-eligible;
• loyalty_tier = gold and purchased recently;
• account_role = admin and setup incomplete;
• email_frequency = weekly for campaign pressure;
• size_preferences contains a full supported value.

Combine stated preferences with behavior. A chosen category from two years ago may be less useful than recent browsing or purchase. Add freshness where needed.

Document segment logic and sample profiles. Negative conditions need special attention: missing is not always the opposite of true.

Use properties in flows

Properties can support:

• entry filters;
• global flow filters;
• conditional splits;
• message personalization;
• internal notifications;
• property update actions.

Choose the control based on timing. A trigger filter decides eligibility at entry. A conditional split can inspect current state later. A flow filter can prevent further messages when the person becomes ineligible. Confirm current platform evaluation behavior and test changes during delays.

Avoid deep branch trees for weak or sparse data. Always provide a default path.

Personalize with fallbacks

Use custom properties only when the customer understands the relevance. A hidden data point can feel intrusive when surfaced without context.

Klaviyo supports lookup syntax for custom profile values. Use the current message personalization reference and preview with profiles that have:

• expected value;
• missing value;
• unexpected or deprecated value;
• multiple list values;
• special characters;
• non-English locale.

Never expose internal codes. Map them to human language. Avoid using a property in a subject line when missing data would produce an awkward or revealing result.

Audit and clean the property model

Quarterly or after major integration changes:

• export property inventory where possible;
• find spelling and case variants;
• identify unused and sparsely populated properties;
• locate conflicting types;
• review sensitive data;
• map dependencies in segments, flows, and templates;
• deprecate safely;
• confirm owners and source health.

Klaviyo may allow many custom properties, but excess fields make segments unreliable and increase privacy and handover complexity.

FAQ

What are Klaviyo custom properties?

They are brand-specific values stored on profiles, such as preferences, sizes, roles, or calculated attributes. They can support segmentation, flow logic, and personalization.

Are custom properties the same as events?

No. Properties describe current profile state. Events record something that happened with time and context. Many lifecycle use cases use both.

Can a custom property store email consent?

A custom field can describe source data, but it is not automatically Klaviyo's supported channel subscription state. Use the platform's consent mechanisms and applicable evidence requirements.

Why does a property not appear in the segment builder?

Klaviyo currently requires the property to exist on at least one profile. Name conflicts and unexpected data types can also cause problems. Inspect a profile and the official reference.

Can I delete unused properties?

Plan deprecation first. Identify segments, flows, templates, reports, and integrations that depend on the field. Stop writes, migrate logic, and then remove or leave documented legacy data according to platform capability.

Build a small, reliable customer data model

Deliver audits Klaviyo properties, defines event and profile contracts, and turns trustworthy data into maintainable segmentation and flows. Request a Klaviyo data model diagnostic.