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 re-checked on November 3, 2026 against the two Klaviyo help pages linked here and in the next section.

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.

Klaviyo's reference also notes that metric reports record profile properties when they are first ingested, while segments recognize the properties currently on the profile. A report filtered on a value that has since changed may therefore not reflect the update.

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. The help center states that there is no limit to the number of custom properties on one profile, and the profile properties reference asks you to keep the total data sent in each profile update below 100 KB.

Klaviyo's current profile property reference says that if a custom property has the same name as a Klaviyo property on your account, you will not be able to segment on it, and recommends avoiding such names. In our reading, a reserved-name list and a naming review help.

Some platform properties cannot be edited by CSV (for example Klaviyo ID, First active, Last active, Profile created on, Date added, Last open, Last click). Do not try to recreate or override these system-managed fields with similarly named custom values.

Consent deserves special treatment. Klaviyo states that a custom property (its example is Shopify's boolean Accepts Marketing property) is separate from a profile's email or SMS subscription status, and that setting it to true does not subscribe someone. A custom property such as sms_opt_in = true is therefore not the platform's channel consent state. 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

Klaviyo states that property names are case-sensitive: changing the spelling or capitalization creates a different property ("gender" and "Gender" become two properties, and "Gender: Male" and "gender: male" are different too). In our reading, also avoid spaces, 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.

Do not 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 asks you to choose a data type when you create a field during a CSV import. The help center mentions text, list, boolean and date types. In our reading, a number stored as a string will not support numeric comparison, and a date stored as inconsistent text will not support time logic.

For CSV uploads, Klaviyo's reference says a list of values must be formatted as an array (for example ["value 1", "value 2"]) and a date must be formatted as YYYY-MM-DD or MM/DD/YYYY, with an optional HH:MM:SS time.

In our reading, 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 says contains can be applied to Text and List properties. For Text, it matches part of a value. For List, it matches a complete item in the list: with a list of baked goods, contains chocolate will not match "chocolate cake". The reference also notes that when values are not consistent across profiles ("Pats", "Patriots", "patriots"), every variant must be accounted for with separate OR conditions. 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. A field connected to a custom profile property stores the response as a custom property, while a field connected to a built-in Klaviyo property such as First Name updates that property instead. For dropdowns, radio buttons and multi-checkboxes, each option has a label (what visitors see) and a value (what Klaviyo stores on the profile). A manage preferences page collects properties from existing subscribers. 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 notes that submitting a new value for the same profile property replaces the previous value, including from a later form step or a repeat submission, while properties not in the new submission keep their values. An export therefore shows stored values, not a history of each submission. If each submission must be retained, Klaviyo recommends a survey tool such as Typeform.

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.

Klaviyo's custom property article says that, to keep profiles' existing subscription status when only adding properties, you should leave consent and consent timestamp columns out of the upload or deselect them during mapping, because importing those columns or choosing Apply bulk consent can change subscription status. The reference adds that imported values replace existing values for the same property, blank cells are skipped, and properties omitted from the import stay unchanged. It also warns that adding new members to the destination list can trigger a flow connected to that list.

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. In our reading, 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

In the segment builder, a property appears under "Properties about someone" once it is present on at least one profile, and Klaviyo suggests a test profile to make it available before you build segments and flows. 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

In our reading, properties can support:

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

Klaviyo's reference says to use profile filters for information stored on the person's profile, and trigger filters for details of the triggering event in an event-triggered flow. It also describes using a date property as a flow trigger, for example a birthday flow set to repeat annually. In our reading, a conditional split is the way to inspect current state later in the flow. Confirm the platform's evaluation behavior and test changes during delays.

Avoid deep branch trees for weak or sparse data. 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 the lookup filter for custom profile values, for example {{ person|lookup:'Hair Color' }}, and its reference suggests also providing a default value with the default filter. Preview with profiles that have:

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

Klaviyo does not recommend placing a custom date property in the default preference pages, since people must enter a date in an accepted format. Do not 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 does not limit the number of custom properties per profile, but in our reading excess fields make segments unreliable and increase privacy and handover complexity. Klaviyo's reference recommends cleaning out properties that are no longer useful. To remove a property from many profiles, it describes a CSV import with a $unset column; to purge a property from the account, contact Klaviyo Support. Deleting a property from one profile does not delete it from other profiles.

Custom properties are only valuable if they are actually being used correctly across your flows and segments, something a free 30-minute Klaviyo audit can confirm on a live call with an expert.

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. A name that conflicts with a Klaviyo property also prevents segmenting on it. 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. Our Klaviyo optimization team can lead that audit. Request a Klaviyo data model diagnostic.