--- title: Klaviyo : Segmentation slug: apis/klaviyo-segmentation docTags: createdAt: 2023-11-07T06:39:24.812Z --- The following guide will walk you through accessing Klevu Smart Recommendation configurations and applying corresponding pre-configured segments to web visitors via the Klevu API. :::hint{type="warning"} To implement Klaviyo segmentation logic with Klevu Smart Recommendations, you need an active subscription to Klaviyo and Klevu Smart Recommendations (with Personalization enabled). ::: The intitial setup and configuration process takes place within the Klevu Merchant Center. Detailed instructions on how to integrate Klaviyo with Klevu Smart Recommendations can be found [here](https://help.klevu.com/support/solutions/articles/5000884090-create-recommendation-banner-with-segments). **There are four key steps to consider:** 1\. Fetch the applicable segments for the visitor 2\. Apply the Segments to the Recommendations configuration 3\. Request and display the Klevu Recommendations banner 4\. Collect Klevu Analytics (impressions and interaction) # 1. Fetch the Applicable Segments for the Visitor Three parameters are necessary to obtain the appropriate visitor segments 1\. Klevu API KEY 2\. Klevu Session ID 3\. Klaviyo Exchange ID :::hint{type="info"} Once the** Klevu Session ID **and the **Klaviyo Exchange ID** have been obtained, they can be stored locally and used in subsequent calls to Klevu for recommendations. ::: :::ApiMethodV2 ```json { "name": "Request Session ID ", "method": "POST", "url": "https://visitor.service.ksearchnet.com/public/1.0//session", "description": "", "tab": "examples", "examples": { "languages": [ { "id": "wmVxgdUkTHR5UU6QKxZM-", "language": "json", "code": "{\"apiKey\":\"\"}\n", "customLabel": "Request Body" } ], "selectedLanguageId": "wmVxgdUkTHR5UU6QKxZM-" }, "results": { "languages": [ { "id": "K6b5-HvEEEnE9ck5mPSaM", "language": "200", "customLabel": "", "code": "{\n \"apikey\": \"\",\n \"sessionId\": \"\",\n \"segmentInfo\": {\n \"segments\": [],\n \"ttl\": 3600\n }\n}" } ], "selectedLanguageId": "K6b5-HvEEEnE9ck5mPSaM" }, "request": { "pathParameters": [], "queryParameters": [], "headerParameters": [], "bodyDataParameters": [ { "name": "apiKey", "kind": "required", "type": "string", "description": "The unique Klevu apiKey ID of the store" } ], "formDataParameters": [] }, "currentNewParameter": { "label": "Body Parameter", "value": "bodyDataParameters" }, "autoGeneratedAnchorSlug": "request-session-id", "legacyHash": "6j8bv0MQ-uKYIsHF8aepi" } ``` ::: :::hint{type="info"} Retain the sessionId value for this user for use in subsequent API calls to Klevu for a maximum of the ttl time. At this point refresh the sessionId so as to retain continuity. ::: ### ### Obtain Klaviyo Exchange ID Klaviyo holds identity and tracking information in a local browser cookie. The exchange\_id is an encrypted identifier for a Klaviyo profile ID. The value is commonly stored within the base64 encoded Klaviyo cookie “\_\_kla\_id” More information can be found on the Klaviyo developer's website: - [Understanding cookies in Klaviyo | Klaviyo Help Center](https://help.klaviyo.com/hc/en-us/articles/360034666712) - [Klaviyo Developers](https://developers.klaviyo.com/en/v1-2/reference/exchange) :::hint{type="info"} Retain the $exchange\_id value for this user for use in subsequent API calls to Klevu. ::: ### ### Obtain Applicable Visitor Segments Use the *session* endpoint to push the Klaviyo **exchangeID** to Klevu. This will allow Klevu to communicate with Klaviyo directly and return the visitor's applied segmentation. :::ApiMethodV2 ```json { "name": "Request Segments", "method": "POST", "url": "https://visitor.service.ksearchnet.com/public/1.0//session", "description": "", "tab": "examples", "examples": { "languages": [ { "id": "WSX4qj-F_MmV8ie6s0rbA", "language": "json", "code": "{\n\t\"apiKey\": \"\",\n\t\"sessionId\": \"\",\n\t\"sessionInfo\": {\n\t\t\"connectorInfo\": [\n\t\t\t{\n\t\t\t\t\"connectorType\": \"klaviyo\",\n\t\t\t\t\"exchangeId\": \"\"\n\t\t\t}\n\t\t]\n\t}\n}", "customLabel": "Request Body" } ], "selectedLanguageId": "WSX4qj-F_MmV8ie6s0rbA" }, "results": { "languages": [ { "id": "MV91_VdMstn2yj9vbd2SY", "language": "200", "customLabel": "", "code": "{\n \"apikey\": \"\",\n \"sessionId\": \"\",\n \"segmentInfo\": {\n \"segments\": [\n \"\",\n \"\",\n \"\"\n ],\n \"ttl\": 173\n }\n}" } ], "selectedLanguageId": "MV91_VdMstn2yj9vbd2SY" }, "request": { "pathParameters": [], "queryParameters": [], "headerParameters": [], "bodyDataParameters": [ { "name": "apiKey", "kind": "required", "type": "string", "description": "The unique Klevu apiKey ID of the store" }, { "name": "sessionId", "kind": "required", "type": "string", "description": "The session ID as obtained in the previous requests", "children": [] }, { "name": "sessionInfo", "kind": "required", "type": "string", "description": "Used to pass details of the session", "children": [] }, { "name": "connectorInfo", "kind": "required", "type": "string", "description": "Used to pass details of the applied connector", "children": [] }, { "name": "connectorType", "kind": "required", "type": "string", "description": "The value should be \"klaviyo\" in this context", "children": [] }, { "name": "exchangeId", "kind": "required", "type": "string", "description": "The vlaue of the Klaviyo exchangeID as previously obtained", "children": [] } ], "formDataParameters": [] }, "currentNewParameter": { "label": "Body Parameter", "value": "bodyDataParameters" }, "autoGeneratedAnchorSlug": "request-segments", "legacyHash": "59_6oxsvOzGf7Pjo6jPPn" } ``` ::: :::hint{type="info"} Retain the **segment** value for this user for use in subsequent API calls to Klevu. ::: :::hint{type="info"} IMPORTANT: The segments may be updated for any given visitor throughout the session. To keep the segments relevant, please request an updated segment list after the **ttl** has expired. ::: # 2. Apply the Segments to the Recommendations Configuration :::hint{type="success"} Please review the section on API [Configurations](docId\:gp_Pf1_nMovk01Kou09nd) for a complete list of applicable parameters to use based on the application/placement of the Recommendation banner. ::: :::ApiMethodV2 ```json { "name": "Use Segments", "method": "GET", "url": "https://config-cdn.ksearchnet.com/recommendations//settings/", "description": "", "tab": "examples", "examples": { "languages": [ { "id": "MSCNaYYDTcNS-YXQIV_dl", "language": "none", "code": "?sids=,,\n", "customLabel": "Query Paramters" } ], "selectedLanguageId": "MSCNaYYDTcNS-YXQIV_dl" }, "results": { "languages": [ { "id": "jQ1mDftyBZv46iKCVqwE2", "language": "200", "customLabel": "", "code": "{\n \"metadata\": {\n \"title\": \"Still Looking For These?\",\n \"recsKey\": \"\",\n \"pageType\": \"HOME\",\n \"logic\": \"RECENTLY_VIEWED\",\n \"maxProducts\": 10,\n \"productThreshold\": 1,\n \"enabled\": true,\n \"spotKey\": \"\",\n \"spotName\": \"Home Spot 1\",\n \"segmentKey\": ,\n \"segmentName\": \"Just Browsing\"\n },\n \"search\": {\n \"basePath\": \".ksearchnet.com/cs/v2/search\",\n \"payload\": \"{\\\"recordQueries\\\":[{\\\"id\\\":\\\"klevuRECSItemList\\\",\\\"typeOfRequest\\\":\\\"SEARCH\\\",\\\"settings\\\":{\\\"typeOfRecords\\\":[\\\"KLEVU_PRODUCT\\\"],\\\"limit\\\":10}}]}\"\n },\n \"templates\": {\n \"base\": \n },\n \"styles\": {\n \"base\": \n },\n \"scripts\": {\n \"recsObject\": \n }\n}" } ], "selectedLanguageId": "jQ1mDftyBZv46iKCVqwE2" }, "request": { "pathParameters": [], "queryParameters": [ { "name": "sids", "kind": "required", "type": "string", "description": "The SegmentIDs returned as segmentInfo.segments within the previous request\n\n,,", "children": [] } ], "headerParameters": [], "bodyDataParameters": [], "formDataParameters": [] }, "currentNewParameter": { "label": "Query Parameter", "value": "queryParameters" }, "autoGeneratedAnchorSlug": "use-segments", "legacyHash": "WEnbiGZowpd4gd4kFRA6o" } ``` ::: :::hint{type="info"} Retain **spotKey**, **spotName**, **segmentKey**, **segmentName** for reference in the following Analytics collection API calls to Klevu. The resulting **search.payload** JSON object will be the query payload used to call Klevu for the recommendations corresponding result set. ::: # # 3. Request and Display the Klevu Recommendations banner Use the provided query structure from the **search.payload** json within the above response to retrieve the Recommendations array from Klevu See the [Klevu Smart Recommendations API Overview](https://docs.klevu.com/apis/smart-recommendations-overview) for details on query specifics. # # 4. Collect Klevu Analytics After the Recommendations have been displayed, collect the analytics to send to Klevu. :::hint{type="info"} Please use the appropriate **event** value for each **event** type - Product recommendation impression: event = **view\_recs\_list ** - Product clicks from recommendation banner: event = **select\_recs\_list** ::: :::ApiMethodV2 ```json { "name": "Recommendation Impression ", "method": "POST", "url": "https://stats.ksearchnet.com/analytics/collect", "description": "", "tab": "examples", "examples": { "languages": [ { "id": "7KHvYGkpZG3Y-ht-CcQkU", "language": "json", "code": "[\n\t{\n\t\t\"event\": \"view_recs_list\",\n\t\t\"event_apikey\": \"\",\n\t\t\"user_profile\": {\n\t\t\t\"session_id\": \"\"\n\t\t},\n\t\t\"event_data\": {\n\t\t\t\"tags\": [\n\t\t\t\t\"recsPageType:HOME\"\n\t\t\t],\n\t\t\t\"list_id\": \"\",\n\t\t\t\"list_name\": \"Still Looking For These?\",\n\t\t\t\"list_logic\": \"RECENTLY_VIEWED\",\n\t\t\t\"spot_id\": \"\",\n\t\t\t\"spot_name\": \"Home Spot 1\",\n\t\t\t\"segment_id\": ,\n\t\t\t\"segment_name\": \"Just Browsing\",\n\t\t\t\"items\": [\n\t\t\t\t{\n\t\t\t\t\t\"item_id\": \"39814\",\n\t\t\t\t\t\"item_name\": \"Lorem Ipsum\",\n\t\t\t\t\t\"price\": \"25.0\",\n\t\t\t\t\t\"currency\": \"USD\",\n\t\t\t\t\t\"item_brand\": \"47\",\n\t\t\t\t\t\"item_variant\": \"39814\",\n\t\t\t\t\t\"item_group_id\": \"67466\",\n\t\t\t\t\t\"index\": 1,\n\t\t\t\t\t\"quantity\": 1\n\t\t\t\t},\n\t\t\t\t{\n\t\t\t\t\t\"item_id\": \"32697\",\n\t\t\t\t\t\"item_name\": \"Gypsum Dolet\",\n\t\t\t\t\t\"price\": \"37.0\",\n\t\t\t\t\t\"currency\": \"USD\",\n\t\t\t\t\t\"item_brand\": \"47\",\n\t\t\t\t\t\"item_variant\": \"32697\",\n\t\t\t\t\t\"item_group_id\": \"83119\",\n\t\t\t\t\t\"index\": 2,\n\t\t\t\t\t\"quantity\": 1\n\t\t\t\t},\n\t\t\t\t{\n\t\t\t\t\t\"item_id\": \"36888\",\n\t\t\t\t\t\"item_name\": \"Dolet Ipsum\",\n\t\t\t\t\t\"price\": \"26.0\",\n\t\t\t\t\t\"currency\": \"USD\",\n\t\t\t\t\t\"item_brand\": \"47\",\n\t\t\t\t\t\"item_variant\": \"36888\",\n\t\t\t\t\t\"item_group_id\": \"69215\",\n\t\t\t\t\t\"index\": 3,\n\t\t\t\t\t\"quantity\": 1\n\t\t\t\t}\n\t\t\t]\n\t\t}\n\t}\n]", "customLabel": "Request Body" } ], "selectedLanguageId": "7KHvYGkpZG3Y-ht-CcQkU" }, "results": { "languages": [ { "id": "WbdkYaM9kWR_k256DR3i4", "language": "200", "customLabel": "", "code": "200 HTTP response code" } ], "selectedLanguageId": "WbdkYaM9kWR_k256DR3i4" }, "request": { "pathParameters": [], "queryParameters": [], "headerParameters": [], "bodyDataParameters": [], "formDataParameters": [] }, "currentNewParameter": { "label": "Body Parameter", "value": "bodyDataParameters" }, "autoGeneratedAnchorSlug": "recommendation-impression", "legacyHash": "0NqYT6QSLmsFyJBiy2YiE" } ``` ::: **** :::ApiMethodV2 ```json { "name": "Recommendation Product Click ", "method": "POST", "url": "https://stats.ksearchnet.com/analytics/collect", "description": "", "tab": "examples", "examples": { "languages": [ { "id": "msv3rtWxyFzZVyTtoUBXr", "language": "json", "code": "[\n\t{\n\t\t\"event\": \"select_recs_list\",\n\t\t\"event_apikey\": \"\",\n\t\t\"user_profile\": {\n\t\t\t\"session_id\": \"\"\n\t\t},\n\t\t\"event_data\": {\n\t\t\t\"tags\": [\n\t\t\t\t\"recsPageType:HOME\"\n\t\t\t],\n\t\t\t\"list_id\": \"\",\n\t\t\t\"list_name\": \"Still Looking For These?\",\n\t\t\t\"list_logic\": \"RECENTLY_VIEWED\",\n\t\t\t\"spot_id\": \"\",\n\t\t\t\"spot_name\": \"Home Spot 1\",\n\t\t\t\"segment_id\": ,\n\t\t\t\"segment_name\": \"Just Browsing\",\n\t\t\t\"items\": [\n\t\t\t\t{\n\t\t\t\t\t\"item_id\": \"39814\",\n\t\t\t\t\t\"item_name\": \"Lorem Ipsum\",\n\t\t\t\t\t\"price\": \"25.0\",\n\t\t\t\t\t\"currency\": \"USD\",\n\t\t\t\t\t\"item_brand\": \"47\",\n\t\t\t\t\t\"item_variant\": \"39814\",\n\t\t\t\t\t\"item_group_id\": \"67466\",\n\t\t\t\t\t\"index\": 1,\n\t\t\t\t\t\"quantity\": 1\n\t\t\t\t}\n\t\t\t]\n\t\t}\n\t}\n]", "customLabel": "Request Body" } ], "selectedLanguageId": "msv3rtWxyFzZVyTtoUBXr" }, "results": { "languages": [ { "id": "2hhH3cihiOYJ7hOJKbV7d", "language": "200", "customLabel": "", "code": "200 HTTP response code" } ], "selectedLanguageId": "2hhH3cihiOYJ7hOJKbV7d" }, "request": { "pathParameters": [], "queryParameters": [], "headerParameters": [], "bodyDataParameters": [], "formDataParameters": [] }, "currentNewParameter": { "label": "Body Parameter", "value": "bodyDataParameters" }, "autoGeneratedAnchorSlug": "recommendation-product-click", "legacyHash": "5c3dC2kDN2Rg_OB5EfBzA" } ``` :::