Integrate a search and merchandising platform

Overview

This resource will help you as you build an integration between a site search, product-discovery, or merchandising platform and Klaviyo. It walks through why search intent belongs in Klaviyo, the recommended integration flow, the search events to send (and how onsite tracking works for mostly-anonymous sessions), the profile properties to sync, the optional pull direction for personalizing results, and the authentication and certification requirements, with an API quick reference at the end.

Why connect your search and merchandising platform to Klaviyo

Search is the purest intent signal a shopper gives a brand. Someone who types "waterproof hiking boots" into the search bar has told you exactly what they want, right now. The brands that get the most out of that don't leave it in a search analytics dashboard. They push it into the platform where they run every channel. When that platform is Klaviyo and search intent lives on the profile, you get measurable wins:

• Trigger flows on search intent. "Searched for a category but didn't buy" is a browse-abandonment flow with sharper intent than a page view. Merchants trigger it from their existing Klaviyo flows.
• Turn zero-result searches into signal. A search that returns nothing is both a merchandising gap for the catalog team and a "we don't carry that yet, here's something close" moment for the shopper.
• Segment on what people look for. Top searched category is an audience a merchant can't build from purchase history alone.
• Personalize results for known customers. The optional pull direction lets a merchant's Klaviyo segments bias search ranking and merchandising for a recognized shopper.
• Stickier merchants. Search intent wired into flows and segmentation is one of the strongest retention signals across the partner program.

Short version: search and discovery behavior from your platform into the Klaviyo profile means the merchant can act on intent, not just purchases, from the same place they run every other channel.

The flow

Search and merchandising is bidirectional, but the two halves are not equal:

• Core, push: your platform → Klaviyo. On-site search and discovery behavior (queries, clicks, zero-result searches, filters) flowing into Klaviyo as events. This is the load-bearing half; build it first.
• Optional, pull: Klaviyo → your platform. Reading Klaviyo segments and profile data to personalize search ranking and merchandising for a known shopper. A strong value-add, covered as the second half below.

Each profile is keyed by email first, with phone where the merchant runs SMS. But search is unusual: most of the signal starts in the browser, before any identity exists. A large share of searches are anonymous, so the way events reach the profile matters as much as the events themselves (see Onsite tracking below). Use the merchant's customer ID as external_id where it's stable, but always identify by email first.

On initial install, no historical backfill of past searches is needed; search is forward-looking. Start writing events from the first session after install.

Events to send

Event names are not prefixed with your platform name. Branded events handle source attribution automatically when events flow through your OAuth token, so the metric name should just describe the action. Use Title Case payload field names ("Search Term", "Results Count") so they read cleanly in the Klaviyo property picker and template editor.

Be deliberate about volume. A search-heavy storefront generates far more query events than purchases or even page views. Fire Searched Site on enter or a short debounce, never per keystroke, and consider emitting only on a meaningful outcome (a click, a zero-result, a filter apply). Naming Viewed Product From Search distinctly (rather than reusing the merchant's existing Viewed Product) keeps search-sourced views from muddying flow triggers.

$value guidance: search and discovery events are intent signals, not transactions. Don't set $value. The one exception to consider is a purchase-attribution event that ties a completed order back to a search session; that can carry $value, mirroring the ad platform guide's conversion event. Most search integrations skip it and let the merchant's commerce platform own Placed Order and revenue.

How merchants use it

• Searched but didn't buy. "Searched Site in last N days" AND NOT "Placed Order since" triggers a nudge flow featuring the searched term or category.
• Zero-result recovery. Search Returned No Results feeds both a merchandising-gap segment for the catalog team and a "here's something similar" flow for the shopper.
• Search-intent segmentation. Segment by {Platform} Top Search Category to send category-specific campaigns to shoppers who've shown search intent but not purchase intent.
• Discovery-abandonment recovery. Clicked Search Result and Viewed Product From Search without a follow-up cart-add triggers a discovery-specific abandonment flow.

Onsite tracking: client-side vs server-side

This category is unusual because most search signal originates from anonymous, in-browser behavior before any identity exists, so the client-side path is the default, not the fallback.

Client-side (default for search and discovery). Load Klaviyo's onsite JavaScript and track events with klaviyo.track("Searched Site", {...}), or call Create Client Event (POST /client/events/) directly from your widget. Client-side calls authenticate with the merchant's public API key (the six-character company/site ID), never a private key or OAuth token, because they run in the browser. Identity resolution is automatic: Klaviyo reads and writes the __kla_id cookie and merges the session under whatever identity later appears (an email captured, or the exchange ID from a clicked email link). You don't resolve identity yourself on this path; Klaviyo does it once the shopper identifies. Use this for raw search and browse telemetry where most sessions are anonymous.

Server-side (Create Event, OAuth token). Use POST /api/events/ for events your backend already knows are tied to a known customer (a saved-search digest, a post-login personalized-results view) or for batched search analytics you've aggregated server-side. You supply the identifier yourself; there's no automatic cookie resolution on this path. If you only have a browser-side exchange ID and need to act on it server-side, resolve it first with GET /api/profiles/?filter=equals(exchange_id,"<value>"), then write the event against that profile.

Rule of thumb: if the event happens in the browser before you know who the shopper is, use the client-side path and let Klaviyo's cookie resolution catch up. If your server already holds the identity, use the server-side Events API.

Note that Klaviyo can't track events for a session it hasn't cookied. An anonymous searcher with the onsite JS blocked, consent declined, or not yet loaded can't be tied to a profile until they identify themselves.

Profile properties to sync (optional)

Optional, written inline on any event. Use Title Case property names prefixed with your platform's name. Replace {Platform} below with the literal name of your platform (e.g., "Acme Last Search Term"). These give the merchant a current-state view of each shopper's search behavior for segmentation.

Implementation notes:

• Profile property writes go through Update Profile (PATCH /api/profiles/{id}/), or are written inline on the event. Inline is the right default.
• Pick property names up front and don't rename them. Renames break every segment, flow, and template that references them.
• Keep dates in ISO 8601 (UTC). Klaviyo treats string-typed dates as strings, which silently breaks date-property segmentation.
• Scrub search terms for PII before writing them. Shoppers sometimes type names or emails into a search box, and you don't want that landing on the profile or in a metric.

Personalizing results with Klaviyo segments (optional)

The optional pull direction lets a merchant's Klaviyo audiences shape what a known shopper sees. Map a segment to a ranking or merchandising rule: a VIP segment gets boosted or curated results, a cart-abandoners segment gets a merchandised banner.

• Populate a picker of syncable audiences with Get Segments and Get Lists.
• Pull membership with Get Profiles for Segment (GET /api/segments/{id}/profiles), or read individual profile properties with Get Profiles.
• There is no webhook for list or segment membership changes today, so maintain a local snapshot and compute a daily diff, exactly the pattern described in the ad platform guide. Apply the resulting membership to your ranking rules keyed by the shopper's identity.

Scopes for the pull direction: segments:read, lists:read, profiles:read.

Auth, scopes, and certification

Build as a public OAuth app for server-side calls. Private API keys are a non-starter for the marketplace. Start with the Create a public OAuth app guide. Client-side tracking is the exception: it uses the merchant's public API key, as described in Onsite tracking.

Key OAuth specifics for search integrations:

• PKCE is required on the authorization code exchange (code_verifier must be included).
• Access tokens are short-lived (1 hour). Refresh tokens are long-lived but rotate on every use. Persist the latest refresh token after every refresh call, or you'll lose the integration on the next refresh.
• Tokens are scoped per Klaviyo account. Merchants with multiple Klaviyo accounts install separately for each.

Scopes to request:

• events:write to emit server-side search events. (Client-side events use the public key and need no scope.)
• profiles:write to write the optional search properties to profiles.
• profiles:read to resolve an exchange ID to a profile, and to read profile properties for personalization.
• segments:read and lists:read only if you build the optional personalization pull direction.
• catalogs:read only if you resolve product data from the merchant's Klaviyo catalog rather than your own product cache.

Don't over-scope. Unused scopes get flagged in marketplace review. Branded metric badges happen automatically when events flow through the OAuth token.

Once functional, submit for App Marketplace review under the Search & Merchandising category. Plan for at least one round of feedback. The review covers OAuth, scopes, install and uninstall validation, and that the integration delivers what your listing claims.

API quick reference

Concrete specs for AI coding assistants and engineers grounding on this doc. The narrative above is the why and the flow. This section is the what-to-actually-type.

Headers (required on every server-side request)

Authorization: Bearer <oauth_access_token>
revision: 2026-07-15
Accept: application/json
Content-Type: application/json

Pin the revision header to a specific date when you ship. Check the API versioning guide for the current latest. Without it you'll get a 400.

Client-side search event (anonymous session)

From your search widget, with Klaviyo's onsite JS loaded. Klaviyo resolves identity from the __kla_id cookie once the shopper identifies.

klaviyo.track("Searched Site", {
  "Search Term": "waterproof hiking boots",
  "Results Count": 24,
  "Search Type": "full"
});

Server-side search event (known profile)

For a search event your backend can attribute to a known customer. Identify by email first.

POST /api/events/

{
  "data": {
    "type": "event",
    "attributes": {
      "properties": {
        "Search Term": "waterproof hiking boots",
        "Results Count": 24,
        "Search Type": "full"
      },
      "time": "2026-06-17T14:22:11Z",
      "unique_id": "srch_7f31a9",
      "metric": {
        "data": {
          "type": "metric",
          "attributes": { "name": "Searched Site" }
        }
      },
      "profile": {
        "data": {
          "type": "profile",
          "attributes": {
            "email": "[email protected]",
            "properties": {
              "{Platform} Last Search Term": "waterproof hiking boots",
              "{Platform} Last Searched At": "2026-06-17T14:22:11Z"
            }
          }
        }
      }
    }
  }
}

Include time (when the event occurred, ISO 8601) and unique_id (a stable identifier for the event, such as your search-session ID) on every server-side event. Klaviyo uses unique_id to deduplicate.

Resolve an exchange ID to a profile

When you hold only a browser-side exchange ID and need to act server-side.

GET /api/profiles/?filter=equals(exchange_id,"<exchange_id>")

Retries

• 429: respect the Retry-After header. Otherwise exponential backoff starting at 1s, cap at 60s, max 5 retries.
• 5xx: same backoff.
• 4xx (other than 429): don't retry. Log and surface to the merchant.

Rate limits

Per-account, not per-app. Search storefronts generate high event volume, so debounce queries, emit on meaningful outcomes, and use Bulk Create Events (POST /api/event-bulk-create-jobs/) for batched server-side delivery. Reserve POST /api/events/ and the client-side path for the real-time hot path. Request per-account increases through Klaviyo Support and CSM before launch if a merchant is at unusual scale.

Glossary

• Klaviyo profile: customer record. Keyed by email, phone, or external ID.
• Klaviyo metric: event type. "Searched Site," "Clicked Search Result," etc. Created automatically on first event ingest.
• Klaviyo segment: dynamic audience computed from rules. The merchant builds these from your search events and properties, and can feed them back to personalize results.
• Onsite JavaScript: Klaviyo's in-browser tracking library, used to send client-side events and resolve anonymous identity via the __kla_id cookie.
• Exchange ID: an encrypted identifier in the __kla_id cookie representing whatever identity Klaviyo knows for a browser. Used to tie an anonymous session to a profile once it resolves.
• Public API key: the six-character site ID used to authenticate client-side calls from the browser. Safe to expose; never use a private key client-side.
• Zero-result search: a query that returns no matches. A merchandising-gap signal and a re-engagement trigger.

Resources

• Klaviyo Developer Portal. Start here for everything.
• Create a public OAuth app
• Klaviyo JavaScript API / Create Client Event
• Create Event / Bulk Create Events / Update Profile
• Get Segments / Get Profiles for Segment / Get Profiles (for the optional personalization pull)
• Integrate an onsite personalization platform (the sibling category for recommendation and content personalization)
• Klaviyo App Marketplace, Search & Merchandising category. The existing set of search and merchandising integrations.
• App Marketplace Review: [email protected]