=== Klaviyo Toolkit === Author: Tribe Interactive Author URI: https://www.madebytribe.com Contributors: tribeinteractive, mvalera Tags: Klaviyo, WooCommerce Subscriptions, Klaviyo Toolkit Requires at least: 5.0 Tested up to: 7.0 Requires PHP: 7.4 Stable tag: 2.1.0 License: GPLv2 or later License URI: https://www.gnu.org/licenses/gpl-2.0.html Triggers additional events with WooCommerce and Klaviyo. == Description == Send additional key metrics events from WooCommerce to Klaviyo, sync WooCommerce Subscription statuses, create abandoned cart coupons and more. == Installation == 1. Download the plugin below 2. Install it on your WordPress site 3. Set your public API key on the plugin's settings page == Developer Hooks == Every metric the plugin sends to Klaviyo passes through a single dispatcher, so developers can extend or react to any event from a theme or add-on without editing the plugin. All hooks fire for every metric, and each also has a per-metric variant. Every hook receives two extras: `$context`, an array of the source objects for that metric (so you do not have to re-fetch them), and `$service`, the Klaviyo service instance, so you can update a profile straight from a callback. Property filters (add, change, or remove data sent to Klaviyo): * `kt_klaviyo_event_properties` — filters properties for every metric. Parameters: `( array $properties, string $metric_name, array $event, array $context, KT_Klaviyo_Service $service )` * `kt_klaviyo_event_properties_{slug}` — filters properties for one metric. Parameters: `( array $properties, array $event, array $context, KT_Klaviyo_Service $service )` Action hooks (run code before/after a send): * `kt_klaviyo_before_send_event` — `( string $metric_name, array $event, array $context, KT_Klaviyo_Service $service )` * `kt_klaviyo_after_send_event` — `( string $metric_name, array $event, bool $sent, array $context, KT_Klaviyo_Service $service )` * `kt_klaviyo_before_{slug}` — `( array $event, array $context, KT_Klaviyo_Service $service )` * `kt_klaviyo_after_{slug}` — `( array $event, bool $sent, array $context, KT_Klaviyo_Service $service )` `{slug}` is the metric name lowercased with non-alphanumeric characters replaced by underscores. Available slugs and the `$context` keys they provide: * `wc_subscription_created` — `subscription`, `item` * `wc_subscription_status_changed` — `subscription`, `item`, `new_status`, `old_status` * `wc_subscription_renewal` — `subscription`, `item`, `last_order` * `wc_subscription_switched` — `subscription`, `order` * `order_status_changed` — `order`, `from_status`, `to_status` * `order_note_added` — `order`, `customer_note` * `user_registration` — `user`, `customer_id` * `viewed_page`, `viewed_product_category`, `viewed_post`, `searched_site` — `details` `$context` may be empty for a custom metric. The primary IDs (SubID, OrderID, PlanID, etc.) are also in `$properties`, so you can still rehydrate an object if needed. The `$service` object exposes `updateProfileByEmail()`, `updateProfile()`, and `getProfileIdByEmail()`. IMPORTANT: do not call `$service->sendEvent()` from inside a hook — the plugin guards against runaway recursion (it stops after a few nested sends and logs), but a send from within a send hook is not a supported pattern. Updating a profile is safe. Example — enrich the renewal event, then set a profile property on success: `add_filter( 'kt_klaviyo_event_properties_wc_subscription_renewal', function ( $properties, $event, $context ) {` ` $subscription = $context['subscription'];` ` $properties['PaymentMethod'] = $subscription->get_payment_method_title();` ` return $properties;` `}, 10, 3 );` `add_action( 'kt_klaviyo_after_wc_subscription_renewal', function ( $event, $sent, $context, $service ) {` ` if ( ! $sent ) { return; }` ` $service->updateProfileByEmail( $event['customer_properties']['$email'], array(` ` 'last-renewal-payment-method' => $context['subscription']->get_payment_method_title(),` ` ) );` `}, 10, 4 );` == Changelog == = 2.1.0 = * New: Developer hooks to extend metric events. Filter the properties sent on any metric, or a specific one, and run code before or after each send. Each hook also receives the metric's source objects (subscription, order, etc.) and the Klaviyo service, so you can add data or update a profile without a re-fetch. See the Developer Hooks section. * New: Optional usage data sharing to help guide future development. Off by default. You choose whether to take part, and you can change your mind anytime from the toggle under Settings > Miscellaneous. No customer or order data is ever sent. * New: A short optional survey when deactivating the plugin, so we can hear what did not work for you. * Compatibility: Tested up to WordPress 7.0 and WooCommerce 10.9.4. = 2.0.5 = * New: Added a Profile Properties setting to turn the subscription ID sync (wc-sub-id) on or off. Off by default. = 2.0.4 = * New: Sync the subscription ID to Klaviyo profiles (wc-sub-id). * Fix: Saving settings on one tab no longer resets settings on other tabs. = 2.0.3 = * Maintenance: Minor stability and versioning improvements. = 2.0.2 = * Fix: Resolved a packaging issue that could prevent the plugin from loading on some server configurations. = 2.0.1 = * Compat: Upgraded Klaviyo PHP SDK from 13.0 to 15.0 (PHP 7.4+ still supported). * Fix: Suppress noisy "wait_seconds parameter is deprecated" warning from Klaviyo SDK client initialization. * UX: Refined admin settings layout — improved alignment, spacing, responsiveness, and documentation links. * UX: Smoother CSS transitions on admin buttons and text elements. * Internal: Refreshed translation template (.pot) and updated copyright to 2026. = 2.0.0 = * Security: Added nonce verification and per-IP rate limiting for public metric AJAX endpoints. * Security: Added nonce verification and per-IP rate limiting for coupon generation/profile update AJAX endpoint. * Security: Added missing nonce verification for subscription product exporter AJAX handler. * Security: Updated frontend AJAX payloads to send security nonces for public/general events and coupon endpoints. * Performance: Optimized subscription exporter progress by caching total subscription count during export batches. * Performance: Fixed exporter processed-count reporting and cleaned up export count transients after completion. * Performance: Restricted admin asset enqueueing to the Klaviyo Toolkit settings page only. * Feature: Added "Order Status Changed" metric event option (renamed from "WC Order Status Changed"). * Feature: Added profile property sync option for last order status fields (LastOrderStatus, LastOrderStatusAt, LastOrderID). * Feature: Added per-setting toggle for subscription profile field syncing with migration fallback preserving legacy behavior. * Feature: Added "User Registration" metric event support with source tracking (`registration_source`). * Feature: Added separate User Registration source controls for My Account and Checkout account creation. * UX: Consolidated metrics into a single "Metrics" settings section, including WooCommerce Subscription metrics. * UX: Added left-side vertical sub-tab navigation to split settings into focused sections. * UX: Added dynamic section-specific classes on `.kt-settings-section-content` for easier section styling. * UX: Improved toggle theming to use WordPress admin theme colors and refined hover/active styling. * UX: Fixed toggle alignment issues, section layout overlap, and equal-height sidebar/content layout behavior. * UX: Improved settings copy and labels, including coupon type labels ("Fixed Discount", "% Discount"). * UX: Refined right sidebar plugin cards into separate `.klaviyo-box` containers and removed extra promo heading text. * UX: Removed "by TRIBE" text from the admin header. = 1.8.8 = * Security: Added CSRF protection to settings form submission with nonce verification * Security: Added nonce verification to export actions (GET-based triggers) * Security: Added nonce verification and capability checks to all exporter AJAX handlers * Performance: Optimized license checks - reduced from too many API calls per day to 1 per day via daily caching * Performance: Moved license check from blocking admin_init to non-blocking WP-Cron background process * Improvement: All settings and export operations now require proper authentication * Improvement: Added proper cleanup of scheduled cron events on plugin deactivation * Improvement: Moved admin menu from top-level navigation to Settings submenu for better WordPress admin organization = 1.8.7 = * Fix: Prevent WC Subscription Created event from firing on backend subscription updates * Fix: Updating subscription status profile fields on backend updates * Fix: Fixing subscription trial detection * Fix: Add correct value field for WC Subscription Renewal metric event * Improvement: Added plan status value to WC Subscription Created event * Improvement: Added additional trial details to WC Subscription Created metric event * Improvement: Add PlanPreviousStatus to WC Subscription Status Changed metric event * Improvement: Add next renewal date as custom profile property for subscription start and renewal events = 1.8.6 = * Fix: Preventing 'wait_seconds parameter' warning from Klaviyo SDK = 1.8.5 = * Improvement: Changed hook for WC Subscription Created event to support backend subscription creation & free subscription creation * Improvement: Added more logging for WC Subscription Created event * Improvement: Added "PlanSubtotal" and "PlanTotal" to WC Subscription Created event * Compatibility: Rolled back dependencies to restore PHP 7.4 compatibility (no longer requires PHP 8.1.0) = 1.8.4 = * Compatibility: Added PHP version check to prevent installation on PHP versions below 8.1.0 * Note: This was a transitional release to prevent errors on PHP 7.4 systems = 1.8.3 = * Fix: Fix compatibility bug with "PlanExpiresAfter" parameter in the "All Products for WooCommerce Subscriptions" extension * Fix: Various PHP 8 deprecation fixes * Fix: Error when expiration date not set * Improvement: Send Searched Site event when search returns no results * Improvement: Added more logging for Searched Site & WC Subscription Created events * Compatibility: Updated Klaviyo SDK version: 13.0.0 - API Revision: 2025-01-15 * Compatibility: WP tested up to 6.7.2 and WC tested up to 9.7.1 = 1.8.2 = * Fix: Clean up public general events js * Fix: Prevent public general events js from loading for logged out users * Feature: Added viewed custom post type event support * Improvement: Added settings and license links to plugin listing * Compatibility: WP tested up to 6.5.5 and WC tested up to 9.0.2 = 1.8.1 = * Fix: Version number fix for updater = 1.8 = * Improvement: Various code cleanup and organizational improvements * Improvement: Added subscription product selection option to exporter * Improvement: Added subscription variation support for exporter * Improvement: Added subscription variation id to profile properties for WC subscription created & WC subscription status changed events * Improvement: Removed legacy subscription events option & support * Improvement: Added support for variation IDs in WC Subscription Created and WC Subscription Status Changed events * Improvement: Added support for variation IDs in the exporter * Improvement: Added option to select subscriptions in the exporter * Compatibility: Updated Klaviyo SDK version: 8.0.0 - API Revision: 2024-05-15 * Compatibility: WP tested up to 6.5.3 and WC tested up to 8.9.1 * Compatibility: Added PHP v7.4 requirement * Compatibility: Added support for PHP 8+ = 1.7 = * Improvement: Added subscription "id" var to "WC Subscription Renewal" Event * Improvement: Added "PlanGifted" var to "WC Subscription Created" Event to track gifted subscriptions better * Improvement: Added total number of subscription orders to "WC Subscription Renewal" Event * Improvement: Added better description text next to license activation button * Improvement: Added logic to prevent temporary "on-hold" status for the "WC Subscription Status Changed" events on renewals * Improvement: Plugin settings UI updates * Fix: Fix compatibility bug with "PlanExpiresAfter" parameter in the "All Products for WooCommerce Subscriptions" extension * Fix: Various PHP 8 deprecation fixes * Fix: Error when expiration date not set * Feature: Now sending subscription status events as custom profile properties * Feature: Added "Order Note Added" new event * Feature: Added "WC Subscription Switched" new event * Feature: Added filter hook for "WC Subscription Created" event * Feature: Added subscription status export tool * Compatibility: Declared support for High-Performance Order Storage (HPOS) * Compatibility: Added translation support for admin = 1.6 = * Feature: Coupon generation feature for Klaviyo profile = 1.5.1 = * Fix: Remove Private Key from the settings page = 1.5 = * Fix: Fix admin header styling * Fix: JS script updated to track and identify general events * Fix: License check condition changes in admin license page * Fix: Change plugin license check hook action to 'init' * Improvement: WC Subscription Renewal Value + Status Changed Value parameter added * Improvement: Use WP REST API instead of admin-ajax * Improvement: Remove "Added To Cart" Event * Improvement: Admin sidebar layout changes * Improvement: PlanExpiresAfter & PlanNextPaymentDate parameter added * Feature: Adding the "next payment date" and "payment interval" fields to WC Subscription Created and Subscription renewal events * Feature: Klaviyo/sdk installed * Feature: Add a setting to grab the actual subscription cancelation/end date * Feature: Added Klaviyo Private API Key option = 1.4 = * Improvement: Make Klaviyo API request secure * Fix: Redirect to single product page for variable subscription product. * Improvement: Added subscription plan ID in WC subscription * Improvement: Subscription ID parameter changes in WC subscription created event * Improvement: Subscription plan expiration date added in WC subscription created event = 1.3.9 = * Fix: Improved syntax error. * Improvement: Updated admin UI = 1.3.8 = * Fix: Improved performance for license checks. = 1.3.7 = * Improvement: Timestamp updated to track real time events. = 1.3.6 = * Bug fix - Add-to-cart issue solved. * Email change to wc recipient for subscription gifting plugin. * License API checks updated for klaviyo toolkit settings page. * Flatsome theme support added. * Add option to move email address field on checkout to above the name fields. * Some admin layout changes. = 1.3.5 = * Bug fix - SSL certificate verification updated. = 1.3.4 = * Bug fixes. = 1.3.3 = * Fixing EDD auto-updater function. = 1.3.2 = * Bug fix - Add to cart JS. = 1.3.1 = * Fixing license deactivation functionality. = 1.3.0 = * Performance update - reduce unnecessary js loads. = 1.2.0 = * Performance update - reduce license server checks. = 1.1.0 = * Bug fix - Klaviyo API connection error. * Bug fix - Legacy plugin activation fatal error. * Bug fix - Removed old updater code. = 1.0.0 = * Initial release.