Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.omneo.io/llms.txt

Use this file to discover all available pages before exploring further.

Profile sync is the core of the integration. It keeps customer attributes, identities and communication preferences aligned between Omneo (your CRM source of truth) and Klaviyo (your marketing platform).

​
How a profile is matched

Whenever a sync runs in either direction, the extension uses a layered matching strategy to find the corresponding profile in the other system:
  1. Stored identity — The Klaviyo profile ID is stored as an Omneo identity (using a configurable identity handle, defaulting to klaviyo). This is the fastest and most reliable match.
  2. Profile ID search — If no identity is stored, the Klaviyo profile is searched using the Omneo profile ID.
  3. Email fallback — As a last resort, the extension searches Klaviyo by email address.
If no match is found, a new profile is created in the destination system and the identity link is recorded so future syncs can use the fast path.

​
Omneo → Klaviyo

When a profile changes in Omneo, an Omneo webhook fires and the extension pushes the change to Klaviyo.

​
What is synced

  • Core attributes: first name, last name, email, mobile phone, address
  • Identities (the Klaviyo profile ID stored back on Omneo)
  • Custom attributes and properties as configured in the extension mapping
  • Communication preferences (email and SMS marketing consent)

​
Profiles that are excluded

Some profiles are never synced to Klaviyo:
  • Profiles with an email containing @example.com (test data)
  • Profiles with emails starting with staff-profile- (internal accounts)
  • Profiles marked as connection profiles
  • Anything matched by the custom profile exclude logic (a JSON Logic expression configured on the extension)

​
Comms preference logic

Omneo holds the source of truth for marketing consent. A profile is considered subscribed to Klaviyo email marketing only if all of the following are true on the Omneo profile:
  • email_promo is not false
  • email_optout is not true
  • email_bounced is not true
SMS marketing follows the same pattern using sms_promo, sms_optout, and sms_bounced.

​
Transactional email support

The Use Email Promo for Subscriptions setting controls whether marketing and transactional email subscription state are separated.
ModeBehaviour
Disabled (default)Only email_optout and email_bounced decide whether a profile receives any email. The email_promo flag is ignored.
Enabledemail_promo controls marketing email status independently. A profile can opt out of marketing but still receive transactional email. email_optout and email_bounced always override and block all email.

​
Never-subscribed detection

Klaviyo distinguishes between profiles that have explicitly chosen a consent state and those who have never made a choice. Omneo uses the email_consent_updated_at and sms_consent_updated_at timestamps to make the same distinction:
  • If the timestamp is null, the profile has never set a consent state. The extension does not push any subscription change for that channel, so Klaviyo leaves the profile in its default NEVER_SUBSCRIBED state.
  • If a timestamp is present, the consent state is treated as explicit and pushed to Klaviyo.

​
Channel-aware change detection

To avoid noisy or accidental subscription updates, the extension only processes consent changes when consent-related fields have actually changed. Email and SMS are evaluated independently — updating only a name or address never re-evaluates subscription status. A full resync event still re-evaluates everything.

​
Hard bounces and email changes

If a profile’s email has hard-bounced in Klaviyo and that email is later changed in Omneo, a brand new Klaviyo profile is created for the new email. The bounced profile’s identity link is removed from Omneo so future syncs use the fresh profile.

​
Duplicate cleanup

If the extension finds more than one Klaviyo profile linked to a single Omneo profile, it merges the duplicates in Klaviyo and keeps the most recent profile as the survivor. Stale identity links are cleaned up automatically.

​
Klaviyo → Omneo

When a profile is created or updated in Klaviyo (via signup, manual add, or any other source), Klaviyo fires a system webhook to the extension, which then upserts the corresponding Omneo profile.

​
What is synced

  • Basic attributes: email, name, phone
  • Communication preferences derived from Klaviyo’s subscription state
  • Custom Klaviyo properties mapped to Omneo attributes
  • A stored identity linking the two profiles for future syncs
Whenever the extension writes a email_promo or sms_promo value back to Omneo, the corresponding email_consent_updated_at / sms_consent_updated_at timestamp is written at the same time. This applies even for profile.added events where the webhook payload itself contains no consent fields — Klaviyo’s live subscription state is fetched and used as the source of truth. A timestamp is only omitted when Klaviyo’s consent value is genuinely null (unknown).

​
Profile deletion and merging

  • Deletion — When an Omneo profile is deleted, the extension removes the matching Klaviyo profile and clears the identity link.
  • Merging — When two Omneo profiles are merged, the surviving Omneo profile inherits the Klaviyo identity. If both profiles had Klaviyo profiles, those are merged in Klaviyo using Klaviyo’s native profile merge.
  • Profiles without a Klaviyo identity link are skipped on deletion (there is nothing to delete).

​
Background processing

All profile sync work runs asynchronously through Cloud Tasks queues. Failures are retried automatically and high-volume scenarios are processed in batches. See Inbound queues for details.