Skip to main content

Klaviyo

Klaviyo is a marketing automation platform that syncs customer profiles and tracks behavioral events from your CommerceBuild store. Use it to trigger personalized email campaigns, segment audiences based on browsing and purchase activity, and automate customer lifecycle messaging.

How to set it up​

Where to find it: Admin → Notification → Klaviyo

When you'd use this: You want to sync customer data to Klaviyo and track events like profile updates, product views, and site activity for targeted email marketing campaigns.

What you need first:

  • A Klaviyo account
  • Your Klaviyo Private API Key (found in Klaviyo under Account → Settings → API Keys)
  • Your Klaviyo Public API Key (required only if using the trackActiveOnSite operation)

Set it up:

  1. Navigate to Admin → Notification → Klaviyo
  2. Enter your Klaviyo Private API Key in the apiKey field
  3. If you plan to track active site sessions, enter your Klaviyo Public API Key in the publicApiKey field
  4. Save the configuration
  5. Enable the operations you want to use (profile sync, event tracking, bulk imports)

Configuration options​

FieldWhat it doesDefaultRequired
apiKeyYour Klaviyo Private API Key, used for authentication in the Authorization headerNoneYes
publicApiKeyYour Klaviyo Public API Key, used for the trackActiveOnSite operationNoneNo (required only for trackActiveOnSite)

Set up event-based notifications​

Where to find it: Admin → Notification → Edit notification

When you'd use this: You want to trigger Klaviyo actions (like sending events or updating profiles) when specific customer activities occur in CommerceBuild, such as new user registrations, product views, or order placements.

Set it up:

  1. Navigate to Admin → Notification
  2. Create or edit a notification
  3. Choose an event from the Trigger when dropdown (for example, when a new user registers)
  4. Select an action from the Then dropdown — the list shows only actions supported by the event you selected
  5. Save the notification

Using it day-to-day:

Once configured, notifications trigger automatically when the selected event occurs. For example, when a new B2C user registers on your site, CommerceBuild can automatically send that event to Klaviyo for lifecycle tracking and campaign automation. Events may take a few minutes to appear in Klaviyo after they're triggered.

Using it day-to-day​

  1. Profile creation and updates happen automatically when customer data changes in CommerceBuild. The integration creates new profiles in Klaviyo or updates existing ones with current email, name, organization, location, and custom properties.

  2. Bulk profile imports allow you to sync multiple customer profiles at once. The integration submits a bulk import job and returns a job ID that you can use to check import status.

  3. Event tracking captures customer behavior like product views, site activity, and custom events. These events appear in Klaviyo's customer timeline and can trigger automated flows.

  4. Product view tracking sends batches of viewed product events to Klaviyo, including product name, ID, URL, and category data for personalized recommendations. If a customer views the same product multiple times within the same hour, CommerceBuild sends only one event to prevent duplicates.

  5. Monitoring bulk imports: Use the getBatchImportJob operation with a job ID to check the status, completed count, failed count, and total count of profiles in a bulk import.

Troubleshooting​

  • "User not found" errors when tracking events: If a username or email address changes in CommerceBuild after an event is queued, the event may fail to process. Ensure profile updates are synchronized to Klaviyo before tracking events for that user.

  • Viewed Product messages not sending: Verify that the product data includes all required fields (description, itemCode, url, categories) and that the user's email is valid. Check that the Viewed Product metric exists in your Klaviyo account.

  • Profile creation fails with status/detail/code errors: The response includes error details from Klaviyo's API. Common causes include invalid email format, missing required fields, or API key permission issues. Check the error code and detail in the response for specific guidance.

  • Bulk import job returns no results: After submitting a bulk import, wait a few moments before checking the job status. Jobs process asynchronously and may show status as "processing" before completing. Use the bulkImportJobId returned from bulkImportProfile to poll getBatchImportJob.

  • Authorization failures: Verify your API key is correct and has the necessary permissions in Klaviyo. The integration uses API revision 2024-07-15, so ensure your key supports that version.

  • Event tracking shows empty properties: Custom event properties must be passed in the correct format. Use the eventProperties array with name/value pairs, and ensure values are properly formatted for JSON output.

  • Events not appearing after new user registration: Check that you've configured a notification with the user registration event as the trigger and a Klaviyo action selected. Events may take a few minutes to appear in the API log and in Klaviyo after the registration occurs.

  • Viewed Product exchanges show as errors but events arrive in Klaviyo: When Klaviyo accepts product view events successfully, it returns an empty response that CommerceBuild may log as an error. Your tracking data is not lost — the events are still recorded in Klaviyo and will appear in customer timelines. This is a cosmetic issue in the exchange log and does not affect your campaigns or event data.