A Klaviyo plugin for Medusa.
A Medusa plugin that integrates Klaviyo's email marketing and customer engagement platform with your Medusa store.
Note: This is a fork of @variablevic/klaviyo-medusa with feature enhancements including event tracking, return management, cart behavioral tracking, enhanced product feed with brand support, and bulk subscription management.
yarn add @eancarr/klaviyo-medusa
Or with npm:
npm install @eancarr/klaviyo-medusa
Then add the plugin to your file:
const plugins = [// ...{resolve: "@eancarr/klaviyo-medusa",options: {apiKey: process.env.KLAVIYO_API_KEY,},},];
| Option | Type | Description | Default |
|---|---|---|---|
| Your Klaviyo API key |
KLAVIYO_API_KEY=your_klaviyo_api_keySTOREFRONT_URL=https://your-storefront-url.com # Optional: Your actual storefront URL (where customers view products). Used for product feed links. Defaults to http://localhost:8000
Once installed and configured, the plugin will automatically track the following events:
The plugin uses Medusa event subscribers to listen for events and send them to Klaviyo:
All events are tracked server-side for reliability and include complete data from your Medusa database. These events can be used in Klaviyo to:
To properly manage marketing consent for Klaviyo in your storefront, you should set consent settings in the customer's metadata. This ensures compliance with privacy regulations by only subscribing customers who have explicitly given consent.
When collecting customer information (during registration, newsletter signup, or checkout), update the customer metadata with Klaviyo consent flags:
// Example implementation in your storefrontconst updateCustomerConsent = async (customerId: string,consentSettings: {email?: boolean;sms?: boolean;transactional_sms?: boolean;consented_at?: string; // ISO date string (optional)}) => {// Call your store API endpoint that updates customer metadataawait fetch("/store/customers/me", {method: "POST",headers: {"Content-Type": "application/json",},credentials: "include",body: JSON.stringify({metadata: {klaviyo: consentSettings, // Can be object or JSON string},}),});};// Usage exampleupdateCustomerConsent("cus_123", {email: true,sms: false,transactional_sms: true,});
The plugin checks for these consent settings when syncing customer data to Klaviyo:
The value can be either:
The plugin provides a Klaviyo-compatible product feed API that allows you to sync your entire product catalog with Klaviyo. This enables product recommendations, abandoned cart emails with product details, and more.
To use the product feed in Klaviyo:
Access your product feed at:
In your Klaviyo account:
The product feed includes comprehensive product data:
You can extend the plugin by:
Example of using the Klaviyo service in your own code:
// Access the Klaviyo serviceconst klaviyoService = container.resolve("klaviyoService");// Create an eventawait klaviyoService.createEvent({metric: {name: "Custom Event",},profile: {email: "customer@example.com",},properties: {// Your custom properties},});// Upsert a customer profileawait klaviyoService.upsertProfile({email: "customer@example.com",phone_number: "+1234567890",// ... other profile attributes});// Bulk subscribe profilesawait klaviyoService.bulkSubscribeProfiles([{type: "profile",id: "profile-id",attributes: {email: "customer@example.com",subscriptions: {email: {marketing: {consent: "SUBSCRIBED",},},},},},]);
# Clone the repositorygit clone https://github.com/eancarr/klaviyo-medusa.git# Install dependenciescd klaviyo-medusayarn# Start development serveryarn dev
MIT