CartPulse AI

AI-Powered Cart Abandonment Prevention for WooCommerce

By Earlybirds — Version 1.0.0

WordPress 6.0+ PHP 7.4+ WooCommerce 8.0+

Table of Contents

  1. Introduction & Overview
  2. Installation & Activation
  3. Setup Wizard
  4. Dashboard
  5. Campaign Management
  6. Trigger Configuration
  7. Intervention Content & Design
  8. Merge Tags Reference
  9. Coupon Configuration
  10. Live Campaign Preview
  11. Campaign Scheduling
  12. Campaign Import / Export
  13. Preset Library
  14. A/B Testing
  15. Spin-to-Win Wheel
  16. Analytics Dashboard
  17. Live Visitors Dashboard
  18. Cart Recovery Emails
  19. Complete Settings Reference
  20. Tools & Diagnostics
  21. REST API Reference
  22. Webhooks
  23. WP-CLI Commands
  24. Hooks & Filters Reference
  25. Privacy & GDPR
  26. How the Storefront Works
  27. Demo Data System
  28. Compatibility
  29. Troubleshooting
  30. FAQ
  31. Changelog
  32. Support & Credits

1. Introduction & Overview

CartPulse AI is a WooCommerce plugin that detects when visitors are about to abandon your store and delivers intelligent, AI-powered interventions to recover lost sales. It combines real-time behavior tracking, exit-intent detection, and optional AI content generation to show the right message at the right moment — turning abandoned carts into completed purchases.

How It Works

  1. Track — The storefront script silently monitors visitor behavior: scroll depth, time on page, cart activity, tab switches, and checkout progress.
  2. Score — An intent scoring engine calculates a 0–100 purchase-intent score in real time based on 12 weighted signals.
  3. Trigger — When behavior matches your campaign rules (exit intent, idle timeout, cart value threshold, etc.), a campaign fires.
  4. Intervene — A personalized popup, slide-in, bar, or spin-to-win wheel appears with the right message and offer.
  5. Convert — Revenue attribution tracks which interventions drove completed purchases, giving you exact ROI data.
  6. Measure — Interactive analytics charts show revenue saved, strategy effectiveness, and funnel performance.

Key Features at a Glance

9 Trigger Types

Exit intent, idle timeout, scroll depth, tab switch, cart value, checkout abandon, URL pattern, referrer match, cart contains.

7 Template Styles

Popup, slide-in, top bar, bottom bar, fullscreen, inline, and spin-to-win wheel.

6 Intervention Strategies

Personalized discounts, free shipping, social proof, urgency, objection handling, value reminders.

AI-Enhanced Content

Optional OpenAI / Anthropic integration for dynamic, context-aware messaging. Works great without AI too.

Visual Analytics

4 Chart.js-powered charts: revenue line, bar, donut, and funnel. CSV export included.

12 Campaign Presets

Ready-made, one-click campaigns covering urgency, discounts, social proof, recovery, and gamification.

A/B Testing

Split test variants with auto-winner detection at a configurable statistical confidence threshold.

Privacy-First

Auto-detects 6 consent plugins, respects DNT, GDPR exporters/erasers, configurable data retention.

Works Without AI

CartPulse AI ships with built-in templates that use merge tags to pull real WooCommerce data (cart totals, recent purchases, product ratings). No API key is required for core functionality. Adding an AI provider (OpenAI or Anthropic) enhances interventions with dynamically generated, context-aware copy. You control costs via a monthly budget cap.

System Requirements

RequirementMinimumRecommended
WordPress6.06.4+
PHP7.48.1+
WooCommerce8.09.0+
MySQL / MariaDB5.7 / 10.38.0 / 10.6
PHP Extensionssodium (for API key encryption)
Memory Limit128 MB256 MB

2. Installation & Activation

Method A — WordPress Admin Upload

  1. Download the cartpulse-ai.zip file from your CodeCanyon purchase.
  2. In WordPress, navigate to Plugins → Add New → Upload Plugin.
  3. Choose the ZIP file and click Install Now.
  4. After installation completes, click Activate Plugin.

Method B — FTP / File Manager

  1. Extract the ZIP file on your computer.
  2. Upload the cartpulse-ai folder to wp-content/plugins/ via FTP or your hosting file manager.
  3. In WordPress, go to Plugins and click Activate next to CartPulse AI.

What Happens on Activation

When you activate CartPulse AI for the first time, the plugin automatically:

  1. Creates 7 database tables — sessions, behavior events, campaigns, intervention logs, analytics, token usage, and cart recovery.
  2. Sets default settings — Safe defaults for tracking, privacy, and behavior configuration.
  3. Registers cron events — 6 scheduled tasks for analytics aggregation, data cleanup, coupon cleanup, schedule processing, optional purchase verification, and cart recovery emails.
  4. Imports demo data — Sample campaigns and 60 days of synthetic analytics data so you can explore all features immediately.
  5. Redirects to the Setup Wizard — A 5-step onboarding wizard guides you through initial configuration.
Tip: Demo data can be cleared at any time from the Dashboard (dismiss banner) or Tools → Clear Demo Data.

3. Setup Wizard (5 Steps)

The setup wizard runs automatically on first activation and can be accessed later from CartPulse AI → Setup Wizard. It has 5 steps:

Step 1 — Preflight Checks

The wizard verifies your environment before proceeding:

CheckRequiredAction if Failed
WooCommerce active (≥ 8.0)YesInstall and activate WooCommerce
PHP version (≥ 7.4)YesUpgrade PHP via your hosting panel
libsodium extensionNo (recommended)Contact host to enable ext-sodium
Database tables installedYesRun migrations from Tools page
Memory limit (≥ 128 MB)No (recommended)Increase in php.ini or wp-config.php

If any required check fails, the Next button is disabled until the issue is resolved.

Step 2 — AI Provider Setup

Configure your AI provider for dynamic content generation. This step is optional — you can skip it and use static templates with merge tags.

Step 3 — Behavior & Privacy

Step 4 — First Campaign

Choose from 3 recommended presets to launch immediately, or skip to configure campaigns manually later:

Step 5 — Done

Summary of your configuration: AI provider status, number of campaigns created, tracking status. Quick links to Dashboard, Campaigns, and Settings pages.

Info: The wizard can be re-run at any time. It will not overwrite existing settings unless you submit a step.

4. Dashboard

The main dashboard provides a high-level overview of your store’s performance. Access it from CartPulse AI → Dashboard.

KPI Cards

Eight stat cards display at the top of the dashboard, each with a colored left border for quick scanning:

CardColorDescription
Revenue SavedGreenTotal revenue attributed to intervention-assisted conversions.
SessionsBlueUnique visitor sessions tracked in the selected date range.
Interventions ShownAmberNumber of times a campaign intervention was displayed.
ConversionsGreenSessions that saw an intervention and completed a purchase.
Conversion RateGreenConversions divided by interventions shown (percentage).
Active CampaignsBlueNumber of currently active campaigns.
AI Budget UsedAmberCurrent month AI API spend vs. budget limit.
ROIGreenRevenue saved divided by estimated AI API cost.

Date Range Picker

Filter all dashboard data by 7-day, 30-day, or 90-day periods using the date range selector in the top-right corner.

Preview Mode

Toggle Preview Mode from the dashboard to test interventions as an admin without affecting live visitors. When enabled, an amber “Preview Mode: ON” indicator appears in the WordPress admin bar on the frontend.

Top Campaigns Table

Shows your top-performing campaigns ranked by conversion rate, with columns for impressions, conversions, revenue, and status.

Demo Data Banner

If demo data is loaded, a dismissible banner appears at the top. Click Clear Demo Data to remove all synthetic data and start fresh with real analytics.

5. Campaign Management

Campaigns are the core building block of CartPulse AI. Each campaign defines when to show an intervention (trigger), what to show (intervention content and design), and who should see it (targeting conditions).

Campaign List

The campaign list page (CartPulse AI → Campaigns) shows all campaigns with:

Creating a Campaign

Click Add New Campaign or apply a preset from the Preset Library. The campaign editor has these sections:

  1. Name & Status — Campaign name (internal), status (draft/active/paused), priority (1–100).
  2. Trigger Configuration — See Section 6.
  3. Intervention Content — See Section 7.
  4. Coupon Configuration — See Section 9.
  5. Design Options — Theme, accent color, animation, border radius.
  6. A/B Testing — See Section 14.
  7. Schedule — See Section 11.

Campaign Fields Reference

FieldTypeDescription
nameTextInternal campaign name (not shown to visitors).
statusSelectdraft, active, paused.
priorityNumber1–100. Higher = evaluated first. Default: 60.
trigger_configObjectTrigger type, frequency, conditions. See Section 6.
interventionObjectTemplate type, content mode, headline, body, CTA, design.
coupon_configObject/nullAuto-generated coupon settings or null for no coupon.
ab_test_configObject/nullVariant B content, split ratio.
schedule_configObject/nullDate range, day-of-week, time window.

6. Trigger Configuration

Triggers define the behavioral signal that causes a campaign’s intervention to fire. Each campaign has exactly one trigger type.

Trigger Types

TypeSlugDescription
Exit Intentexit_intentFires when the mouse cursor leaves the viewport toward the browser bar (desktop) or rapid scroll-up (mobile).
Idle Timeoutidle_timeoutFires after N seconds of no interaction while items are in the cart. Configure timeout_seconds.
Scroll Depthscroll_depthFires when the visitor scrolls past a configured percentage of the page. Configure scroll_pct (e.g., 60).
Tab Switchtab_switchFires when the visitor switches to a different browser tab (comparison shopping signal).
Cart Valuecart_valueFires when the cart total exceeds a threshold. Configure cart_value_threshold.
Checkout Abandoncheckout_abandonFires when the visitor shows signs of leaving the checkout page without completing the order.
URL Patternurl_patternFires on pages matching a URL pattern (e.g., /product/sale-*).
Referrer Matchreferrer_matchFires when the visitor arrived from a specific referrer domain (e.g., google.com).
Cart Containscart_containsFires when the cart contains specific product IDs or category slugs.

Frequency Options

FrequencyDescription
alwaysFire every time the trigger condition is met.
once_per_sessionFire only once per visitor session.
once_per_dayFire at most once per calendar day per visitor.
once_per_visitorFire only once ever per visitor (cookie-based).

Targeting Conditions

Each trigger supports additional conditions that must be met alongside the trigger event:

ConditionDescription
min_intent_scoreMinimum purchase-intent score (0–100) the visitor must have.
min_cart_valueMinimum cart value (in store currency) before the trigger fires.
device_typeall, desktop, or mobile.
page_typeall, product, category, cart, checkout, shop, or other.

7. Intervention Content & Design

Template Types

TypeSlugDescription
PopuppopupCentered modal overlay with headline, body, CTA buttons, and optional close button.
Slide-inslide_inSmall panel that slides in from the bottom-right corner of the viewport.
Top Bartop_barFull-width notification strip at the top of the page.
Bottom Barbottom_barFull-width notification strip at the bottom of the page.
FullscreenfullscreenFull-viewport overlay with centered content and background dimming.
InlineinlineEmbedded directly in the page content (non-overlay).
Spin Wheelspin_wheelGamified spinning wheel with configurable prize slices. See Section 15.

Content Mode

Content Fields

FieldDescription
headlineMain heading text displayed at the top of the intervention.
bodyBody copy supporting the headline.
cta_textPrimary call-to-action button label.
cta_actionWhat happens on CTA click: apply_coupon, redirect, close, or spin.
cta_urlURL to redirect to (when cta_action is redirect). Defaults to cart page.
secondary_cta_textOptional dismiss button text (e.g., “No thanks”).

Design Options

OptionValuesDescription
Themelight, dark, brandColor scheme for the intervention panel.
Accent ColorHex colorApplied to CTA buttons and borders.
Border RadiusPixelsCorner rounding for the intervention container.
Overlay Opacity0–1Background dimming for popup/fullscreen types.
Animationfade, fade-up, slide, slide-left, bounceEntry animation when the intervention appears.
Tip: All design changes are previewed in real time in the Live Campaign Preview panel.

8. Merge Tags Reference

Merge tags allow static templates to display dynamic, real-time data from your store. Insert them in headline, body, or CTA text fields.

TagDescriptionExample Output
{cart_total}Current cart total in store currency.$89.99
{cart_count}Number of items in the cart.3
{product_name}Name of the first product in the cart.Premium Wireless Headphones
{discount_amount}The coupon discount value (from coupon config).10%
{savings_display}Calculated savings amount in currency.$9.00
{expiry_hours}Hours until the coupon expires.24
{recent_purchases}Real WooCommerce order count in the last 24 hours.47
{recent_buyers}Unique customers who ordered in the last 24 hours.23
{product_rating}Average product rating (from WooCommerce reviews).4.7
{review_count}Number of product reviews.128
{store_name}Your store/site name from WordPress settings.My Store
{shipping_gap}Amount remaining to reach free shipping threshold.$11.01
{shipping_threshold}Free shipping threshold from plugin settings.$100.00
{coupon_code}The auto-generated coupon code.FLASH-A1B2C3
Note: Social proof tags ({recent_purchases}, {recent_buyers}, {product_rating}, {review_count}) pull real data from your WooCommerce orders and product meta. Data is cached for 15 minutes.

9. Coupon Configuration

Campaigns can auto-generate unique WooCommerce coupons for discount-based interventions. Configure the coupon in the campaign editor under Coupon Settings.

FieldDescription
Discount Typepercent (percentage off), fixed (fixed amount off), or free_shipping.
AmountDiscount value (e.g., 10 for 10% or $10).
PrefixCoupon code prefix (e.g., FLASH produces FLASH-A1B2C3).
Expiry (hours)Hours until the coupon expires after creation (1–168). Default: 24.

How It Works

  1. When an intervention is shown, the plugin creates a unique WooCommerce coupon with the configured discount type, amount, and expiry.
  2. The coupon code is injected into the intervention via the {coupon_code} merge tag or the CTA “Apply Coupon” action.
  3. The coupon is a standard WooCommerce coupon — it appears in Marketing → Coupons and works with all WooCommerce checkout flows.
  4. Expired coupons are automatically cleaned up by a daily cron job (earlybirds_cp_cleanup_coupons).
Existing Coupons: You can also reference an existing WooCommerce coupon code in your static template text instead of using auto-generation.

10. Live Campaign Preview

The campaign editor includes a real-time preview panel on the right side. It uses the same CSS and HTML as the storefront, scaled to 65% for a desktop-like viewport.

What Updates Live

Supported Template Types

All 7 template types are supported in the preview. The spin wheel shows a mini conic-gradient preview that updates as you add/remove slices or change colors.

11. Campaign Scheduling

Campaigns can be scheduled to run during specific time periods. Configure scheduling in the campaign editor under Schedule.

FieldDescription
Start DateCampaign becomes eligible to fire on this date (inclusive). Leave blank for “immediately”.
End DateCampaign stops firing after this date. Leave blank for “indefinitely”.
Day of WeekArray of days (Mon–Sun) when the campaign is active. Leave empty for all days.
Time WindowStart and end time (HH:MM, 24-hour) within each active day. Leave blank for all-day.

Campaigns outside their scheduled window are silently skipped without changing their status. An hourly cron job (earlybirds_cp_process_schedules) evaluates schedule rules.

Tip: Combine scheduling with seasonal campaigns — e.g., a Black Friday campaign active only Nov 24–30, or a weekend-only flash sale.

12. Campaign Import / Export

Exporting

From the campaign list, click Export Campaigns. This downloads a JSON file containing all campaigns with IDs stripped and statuses set to draft. The file is portable and can be imported on any CartPulse AI installation.

Importing

  1. Click Import Campaigns on the campaign list page.
  2. Select a JSON file previously exported from CartPulse AI.
  3. The plugin validates the file structure and creates all campaigns as drafts.
  4. Review and activate imported campaigns individually.
Note: Coupon configurations are imported but coupons are not created until the campaign fires. A/B test stats are not imported.

13. Preset Library

CartPulse AI includes 12 ready-made campaign presets covering the most common abandonment recovery scenarios. Access them from Campaigns → Presets.

#Preset NameCategoryTriggerTypeDescription
1Flash Urgency CountdownUrgencyExit IntentPopupCountdown timer popup with 10% coupon on exit intent.
2Free Shipping NudgeFree ShippingCart ValueTop BarShows how close the visitor is to free shipping.
3Social Proof Trust BoostSocial ProofIdle TimeoutSlide-inRecent purchase activity slide-in after 30s idle.
4Personalized Discount OfferDiscountsExit IntentPopupAI-generated personalized discount with 10% coupon.
5Return Policy ReassuranceRecoveryCheckout AbandonPopupAddresses objections with policy reassurance.
6Cart Value ReminderUrgencyScroll DepthSlide-inReminds visitors of items in cart at 60% scroll.
7Mobile Quick ExitUrgencyExit IntentPopupLightweight popup optimized for mobile exit.
8High-Value Cart VIP OfferDiscountsCart ValueFullscreenAI-generated VIP discount for carts over $100.
9Sticky Discount BarDiscountsExit IntentBottom BarPersistent discount code in bottom bar (desktop).
10Testimonial Trust PopupSocial ProofTab SwitchPopupCustomer testimonial shown when tab switching.
11Checkout Recovery OfferRecoveryCheckout AbandonPopupAI-generated 15% discount for checkout abandoners.
12Spin to WinGamificationExit IntentSpin WheelInteractive spinning wheel with configurable prizes.

Presets are created as draft campaigns. Review the configuration and activate when ready.

14. A/B Testing

Creating an A/B Test

  1. Open an existing campaign or create a new one.
  2. Click Add Variant in the campaign editor.
  3. Configure Variant B’s headline, body, CTA, coupon, and design independently from the control (Variant A).
  4. Set the Split Ratio (e.g., 50/50 or 70/30) — this determines what percentage of qualifying sessions see each variant.
  5. Save and activate the campaign.

How Visitors Are Assigned

Assignment is deterministic — based on a hash of the session ID and campaign ID. This ensures the same visitor always sees the same variant, even across page loads.

Reading A/B Results

In the campaign editor, a results comparison card shows side-by-side stats for each variant:

MetricDescription
ImpressionsNumber of times this variant was shown.
ClicksCTA button clicks.
ConversionsSessions that purchased after seeing this variant.
Conversion RateConversions / Impressions as a percentage.
RevenueTotal order value from converting sessions.
ConfidenceStatistical significance level (shown when sample size is sufficient).

Auto-Winner Detection

When a variant reaches the configured statistical confidence threshold and minimum sample size, the system declares it the winner. Optionally, the losing variant is deactivated automatically.

Tip: Run each variant for at least 7 days before drawing conclusions. Low-traffic stores may need 2–4 weeks for reliable results.

15. Spin-to-Win Wheel

The spin-to-win wheel is a gamified intervention that can increase engagement compared to standard popups. Visitors spin the wheel to win a discount or prize.

Configuration

SettingDescription
Slices3 to 8 slices. Each slice has its own label, color, discount type, amount, and probability weight.
LabelText shown on the slice (e.g., “10% Off”, “Free Shipping”, “Try Again”).
ColorBackground color for the slice (hex value).
Discount Typepercent, fixed, free_shipping, or none (for “Try Again” slices).
Discount AmountValue of the discount (e.g., 10 for 10%).
Probability WeightRelative likelihood of landing on this slice. Weights are auto-normalized to 100%.

How It Works

  1. Visitor clicks the CTA button (“Spin Now”).
  2. The server determines the winning slice based on probability weights.
  3. The wheel animates to land on the winning slice.
  4. If the winning slice has a discount, a WooCommerce coupon is generated and displayed to the visitor.
  5. The visitor can copy the code or click “Apply” to add it to their cart.

Preview

A mini conic-gradient preview updates in real time in the campaign editor as you add, remove, or modify slices.

Note: Each visitor can only spin once per session (rate-limited server-side). The “Try Again” slice type does not generate a coupon.

16. Analytics Dashboard

The analytics dashboard (CartPulse AI → Analytics) provides detailed performance metrics with interactive Chart.js-powered visualizations.

Charts

ChartTypeDescription
Revenue SavedLine chart (filled area)Revenue saved over time. Hover for daily amounts.
Interventions vs ConversionsBar chartSide-by-side bars per day: interventions shown (indigo) vs converted (green).
Conversions by StrategyDonut chartWhich intervention strategies drive the most conversions.
Checkout FunnelHorizontal barVisit → Cart → Checkout → Payment → Order with percentage at each stage.

Summary Metrics

Campaign Performance

Below the charts, a table breaks down performance per campaign with columns for impressions, clicks, conversions, conversion rate, and revenue attributed. A/B test variants appear as sub-rows.

Intent Distribution

A histogram showing the distribution of visitor intent scores (0–100) helps you understand your traffic’s engagement level.

Date Range & Export

Email Digests

Enable Weekly Digest under Settings to receive a summary email every Monday with the previous week’s key metrics. Revenue milestone alerts can also be configured.

17. Live Visitors Dashboard

The live visitors page (CartPulse AI → Live Visitors) shows a real-time view of active visitors on your store.

Per-Visitor Data

ColumnDescription
Session IDAnonymous session identifier (truncated for display).
PageCurrent page the visitor is viewing.
Page TypeProduct, cart, checkout, category, shop, or other.
Intent ScoreReal-time purchase intent score (0–100) with a progress bar.
Cart ValueCurrent cart total in store currency.
DeviceDesktop or Mobile.
DurationTime since session started.
StatusHot (intent ≥ 60), Warm (intent 30–59), or Browsing (intent < 30).

Auto-Refresh

The dashboard auto-refreshes every 15 seconds via the REST API. No manual refresh is needed.

18. Cart Recovery Emails

CartPulse AI can send automated recovery emails to visitors who abandon their carts. This feature works alongside real-time interventions to recover sales even after the visitor has left.

Settings

SettingDescription
EnabledToggle cart recovery emails on/off.
Delay (minutes)How long to wait after cart abandonment before sending the email (default: 60).
Coupon EnabledInclude an auto-generated discount coupon in the recovery email.
Coupon TypePercent or fixed discount.
Coupon AmountDiscount value for the recovery coupon.
Email SubjectCustom subject line for the recovery email.

How It Works

  1. When a session with items in the cart expires without a purchase, a recovery record is created.
  2. An hourly cron job checks for pending recovery records that have passed the delay threshold.
  3. The recovery email is sent with a unique recovery link (?cp_recover=TOKEN).
  4. Clicking the link restores the visitor’s cart and redirects them to the cart page.
  5. Old recovery records (7+ days) are automatically expired and cleaned up.
Note: Cart recovery emails require the visitor to have provided their email address (e.g., at checkout or via an email capture intervention).

19. Complete Settings Reference

All settings are under CartPulse AI → Settings.

General

SettingDefaultDescription
EnabledYesMaster switch for all tracking and interventions.
Debug ModeNoEnables verbose logging to WooCommerce → Status → Logs. Disable in production.

AI Configuration

SettingDefaultDescription
AI Provider(none)OpenAI or Anthropic. Leave blank to use static templates only.
OpenAI API KeyEncrypted at rest using libsodium. Never displayed after saving.
Anthropic API KeyEncrypted at rest using libsodium. Never displayed after saving.
Model(auto)Model for AI content generation (e.g., gpt-4o, claude-3-haiku).
Monthly Budget (USD)$50.00Hard cap on AI API spending. Range: $0–$10,000.
Default ToneFriendlyFriendly, Professional, Urgent, or Casual. Overridable per campaign.
Default LanguageEnglishLanguage for AI-generated text. Overridable per campaign.

Obtaining an API Key

ProviderWhere to Get a Key
OpenAIplatform.openai.com → API Keys → Create new secret key
Anthropicconsole.anthropic.com → API Keys → Create Key

Behavior Tracking

SettingDefaultDescription
Session Timeout (minutes)30Minutes of inactivity before a session expires. Range: 1–1440.
Batch Interval (ms)5000How often the storefront sends behavior events to the server. Range: 1000–60000.
Max Interventions per Session2Maximum number of interventions shown in one session. Range: 1–10.
Intervention Cooldown (seconds)60Minimum time between showing two interventions. Range: 0–3600.
Intent Weights(defaults)Custom weights for the 12 intent scoring signals. Auto-normalizes to 100.

Privacy

SettingDefaultDescription
Cookie ConsentAuto-detectAuto-detect: checks for CookieYes, Complianz, Cookie Notice (dFactory), Borlabs Cookie, CookieBot, WP Consent API. WP Consent API: uses only the WP Consent API standard. None: always track (not recommended in EU).
Consent CategoryStatisticsWhich consent category must be accepted: Statistics or Marketing.
Respect Do Not TrackYesHonor the browser DNT header.
Data Retention (days)30Days to keep behavior events and session data. Range: 1–365. A daily cron purges older records.
Delete Data on UninstallNoWhen enabled, all plugin tables and options are removed on plugin deletion.

Store Context

SettingDefaultDescription
Free Shipping Threshold0Cart value required for free shipping. Used by the {shipping_gap} and {shipping_threshold} merge tags.
Return Policy(blank)Summary of your return policy. Provided to AI for objection handling prompts.
Shipping Policy(blank)Summary of your shipping policy. Provided to AI prompts.
Guarantees(blank)Satisfaction guarantees. Provided to AI prompts.

Notifications

SettingDefaultDescription
Weekly DigestOffSend a weekly performance summary email every Monday.
Digest RecipientsAdmin emailComma-separated email addresses for the digest.
Revenue Milestone AlertsOnNotify when revenue saved reaches significant milestones.

Integrations

SettingDefaultDescription
GA4 Measurement ID(blank)Google Analytics 4 measurement ID (G-XXXXXXXXXX) for event tracking.
Webhook URL(blank)Endpoint URL for webhook delivery.
Webhook Secret(blank)Shared secret for HMAC-SHA256 signature verification.
Webhook Eventsintervention.shown, intervention.converted, order.attributedEvents that trigger webhook delivery.

Excluded Roles & Pages

SettingDefaultDescription
Excluded RolesAdministrator, Shop ManagerThese roles never see interventions or get tracked (unless Preview Mode is on).
Excluded Pages(none)Specific page IDs or slugs to skip.
Trusted Proxy IPs(none)If behind a load balancer, list proxy IPs so rate limiting uses the real client IP.

License

SettingDescription
Purchase CodeYour CodeCanyon/Envato purchase code (UUID). Used to verify your purchase for updates and support.
Verification StatusVerified, Unverified, or Invalid. Checked periodically against the Envato API.

Cart Recovery

SettingDefaultDescription
Enable Cart RecoveryOffToggle automated cart recovery emails.
Delay (minutes)60Wait time before sending recovery email.
Recovery CouponOffInclude an auto-generated coupon in the email.
Coupon TypePercentPercentage or fixed amount discount.
Coupon Amount10Discount value.
Email Subject(default)Custom subject line for recovery emails.

20. Tools & Diagnostics

The Tools page (CartPulse AI → Tools) provides system diagnostics, maintenance actions, a log viewer, and a support bundle generator.

System Status Checks

A comprehensive status table displays 15+ environment checks:

CheckWhat It Verifies
PHP VersionPHP ≥ 7.4
WordPress VersionWP version reported
WooCommerce VersionWC is active and version
MySQL VersionDatabase server version
Memory Limit≥ 128 MB recommended
Max Execution TimePHP max_execution_time
libsodiumsodium extension available for encryption
REST APIWordPress REST API is reachable
WP-CronNot disabled by DISABLE_WP_CRON
AI ConfiguredAt least one API key is set
Active CampaignsNumber of active campaigns
DB Tables (5+)Each plugin table exists
Cron Events (5)Each cron hook is scheduled with next run time

Click Copy to Clipboard to copy the full status as JSON for support requests.

Maintenance Tools

ToolDescriptionConfirmation Required
Flush CacheClear all plugin cache entries.No
Run MigrationsRe-run database migrations (safe to run multiple times).No
Clear SessionsTruncate the sessions table.Yes
Clear Behavior EventsTruncate the behavior events table.Yes
Clear Token UsageReset AI token usage tracking.Yes
Regenerate Webhook SecretGenerate a new random webhook signing secret.Yes
Clear Demo DataRemove all imported demo campaigns and analytics.Yes

Log Viewer

View the last 200 lines of the plugin log file (stored in WooCommerce’s log directory). Filter by level: All, Error, Warning, Info, or Debug. Download the full log or clear it.

Support Bundle

Click Generate Support Bundle to download a ZIP containing:

21. REST API Reference

CartPulse AI exposes a comprehensive REST API under the namespace earlybirds-cp/v1. All admin endpoints require authentication via cookie+nonce or application password with manage_woocommerce capability.

Base URL: https://yoursite.com/wp-json/earlybirds-cp/v1/

Campaigns

MethodEndpointDescription
GET/campaignsList all campaigns (supports status filter, pagination).
POST/campaignsCreate a new campaign.
GET/campaigns/{id}Get a single campaign by ID.
PUT/campaigns/{id}Update a campaign.
DELETE/campaigns/{id}Delete a campaign.
POST/campaigns/importImport campaigns from JSON.
GET/campaigns/exportExport all campaigns as JSON.

Analytics

MethodEndpointDescription
GET/analytics/summarySummary metrics for a date range.
GET/analytics/dailyDaily breakdown of metrics.
GET/analytics/campaignsPer-campaign performance breakdown.
GET/analytics/funnelCheckout funnel data.
GET/analytics/strategiesConversions by intervention strategy.
GET/analytics/intent-distributionIntent score histogram.
GET/analytics/exportCSV download of analytics data.

Behavior (Public)

MethodEndpointAuthDescription
POST/behavior/sessionNonceCreate or resume a visitor session.
POST/behavior/eventsNonceBatch-submit behavior events.
POST/behavior/heartbeatNonceKeep session alive.

Interventions

MethodEndpointDescription
POST/interventions/evaluateEvaluate campaigns and return matching intervention.
POST/interventions/shownLog an intervention impression.
POST/interventions/dismissedLog an intervention dismissal.
POST/interventions/clickedLog a CTA click.
POST/interventions/spinExecute a spin-to-win wheel spin.

Settings (Admin)

MethodEndpointDescription
GET/settingsGet all settings (API keys masked).
PUT/settingsUpdate settings (partial update supported).
POST/settings/test-connectionTest AI provider connection.
GET/system/statusStructured system health checks.

Live Visitors (Admin)

MethodEndpointDescription
GET/live-visitorsActive sessions with intent scores, cart values, and page info.

Cart Recovery (Admin)

MethodEndpointDescription
GET/cart-recoveryList pending and sent recovery records.
DELETE/cart-recovery/{id}Delete a recovery record.

Rate Limiting

All endpoints are rate-limited: 60 requests/minute for general endpoints, 10 requests/minute for AI-related endpoints. Rate limit headers (X-RateLimit-Limit, X-RateLimit-Remaining) are included in responses.

22. Webhooks

Webhooks push real-time events to external systems such as Zapier, Make, or custom endpoints.

Supported Events

EventWhen Fired
intervention.shownAn intervention was displayed to a visitor.
intervention.convertedA visitor who saw an intervention completed a purchase.
order.attributedAn order was attributed to a CartPulse AI session.
campaign.updatedA campaign was created, updated, or status changed.

Payload Format

{
  "event": "intervention.shown",
  "timestamp": "2026-02-18T14:30:00Z",
  "plugin_version": "1.0.0",
  "data": {
    "session_id": "abc123",
    "campaign_id": 42,
    "variant_id": 1,
    "cart_value": "59.99"
  }
}

HMAC-SHA256 Signature Verification

When a Webhook Secret is configured, every request includes an X-CartPulse-Signature header containing an HMAC-SHA256 hash of the raw request body.

PHP Verification Example

$body      = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_CARTPULSE_SIGNATURE'] ?? '';
$expected  = hash_hmac('sha256', $body, YOUR_SECRET_KEY);

if ( ! hash_equals($expected, $signature) ) {
    http_response_code(401);
    exit('Invalid signature');
}

Security

23. WP-CLI Commands

CartPulse AI registers WP-CLI commands under the wp earlybirds namespace.

# Run database migrations (safe to run multiple times)
wp earlybirds migrate

# Flush all plugin cache entries
wp earlybirds cache:flush

# Show plugin status (version, DB version, license, AI provider)
wp earlybirds status

# Export all settings to a JSON file
wp earlybirds settings:export --file=/path/to/settings.json

# Import settings from a JSON file
wp earlybirds settings:import --file=/path/to/settings.json
CommandDescription
wp earlybirds migrateCreate or upgrade plugin database tables to the current schema version. Safe to re-run.
wp earlybirds cache:flushDelete all cached objects created by this plugin (does not affect other WP object cache entries).
wp earlybirds statusDisplay plugin version, database schema version, license status, AI provider, and rate-limiter stats.
wp earlybirds settings:exportWrite current settings to a JSON file. API keys are excluded for security.
wp earlybirds settings:importRestore settings from a previously exported JSON file. Does not overwrite API keys.

24. Hooks & Filters Reference

CartPulse AI provides action hooks and filters for developers to extend or modify plugin behavior.

Actions

HookParametersDescription
earlybirds_cp_intervention_shown$campaign_id, $session_id, $variant_idFired when an intervention is displayed to a visitor.
earlybirds_cp_intervention_converted$campaign_id, $session_id, $order_idFired when an intervention session results in a purchase.
earlybirds_cp_campaign_created$campaign_id, $dataFired after a new campaign is created.
earlybirds_cp_campaign_updated$campaign_id, $dataFired after a campaign is updated.
earlybirds_cp_coupon_generated$coupon_code, $campaign_idFired after an auto-generated coupon is created.
earlybirds_cp_session_started$session_idFired when a new tracking session begins.

Filters

HookParametersReturnDescription
earlybirds_cp_storefront_config$configarrayModify the configuration object passed to the storefront JavaScript.
earlybirds_cp_ai_prompt$prompt, $contextstringModify the AI prompt before it is sent to the provider.
earlybirds_cp_intervention_content$content, $campaignarrayModify intervention content (headline, body, CTA) before rendering.
earlybirds_cp_should_track$should_trackboolOverride whether the current visitor should be tracked.
earlybirds_cp_coupon_args$args, $campaignarrayModify WooCommerce coupon arguments before creation.
earlybirds_cp_intent_weights$weightsarrayModify intent scoring signal weights.

Example: Override Tracking for Custom Conditions

add_filter( 'earlybirds_cp_should_track', function( $should_track ) {
    // Don't track visitors from internal IP range.
    $ip = $_SERVER['REMOTE_ADDR'] ?? '';
    if ( strpos( $ip, '10.0.' ) === 0 ) {
        return false;
    }
    return $should_track;
} );

Example: Modify AI Prompt

add_filter( 'earlybirds_cp_ai_prompt', function( $prompt, $context ) {
    // Add seasonal context to AI prompts.
    $prompt .= "\nNote: We are currently running a summer sale.";
    return $prompt;
}, 10, 2 );

25. Privacy & GDPR

Data Stored Locally

All data collected by CartPulse AI is stored in your WordPress database — no data is sent to Earlybirds servers. The following tables are created:

TableContents
{prefix}cp_sessionsAnonymous session ID, entry time, cart value, device type.
{prefix}cp_behavior_eventsBehavior events: page views, scroll depth, idle time, exit signals.
{prefix}cp_intervention_logsWhich campaign/variant was shown, dismissal or conversion outcome.
{prefix}cp_analyticsAggregated daily metrics per campaign.
{prefix}earlybirds_cp_token_usageAI API token consumption per request (used for budget tracking).
{prefix}earlybirds_cp_campaignsCampaign configurations (admin-created data, not visitor data).
{prefix}cp_cart_recoveryCart recovery records with cart contents and recovery tokens.

What Is Sent to AI Providers

When AI content is requested for an intervention, the plugin sends a prompt containing:

Never sent: Customer names, email addresses, order IDs, payment details, IP addresses, or any PII.

Cookie Consent Integration

CartPulse AI auto-detects 6 popular cookie consent plugins:

  1. CookieYes
  2. Complianz
  3. Cookie Notice (by dFactory)
  4. Borlabs Cookie
  5. CookieBot
  6. WP Consent API

Tracking is gated until the visitor accepts the configured consent category (Statistics or Marketing). If no supported consent plugin is detected in “auto” mode, tracking starts immediately.

Do Not Track (DNT)

When enabled in settings, the plugin respects the browser’s DNT: 1 header. Visitors with DNT enabled will not be tracked and will not see interventions.

WordPress Privacy API

CartPulse AI integrates with Tools → Export Personal Data and Tools → Erase Personal Data. When a user requests export or erasure, the plugin includes or removes all session and event records linked to that user’s ID or email.

Data Retention

Set a retention period (1–365 days) under Settings → Privacy. A daily cron job (earlybirds_cp_cleanup_behavior) purges records older than the configured threshold.

Uninstall Cleanup

When Delete Data on Uninstall is enabled, all plugin tables, wp_options entries, and scheduled tasks are removed when the plugin is deleted from the Plugins screen.

26. How the Storefront Works

The storefront is a lightweight JavaScript module (~15 KB gzipped) that runs on the frontend of your WooCommerce store.

Script Loading

  1. The StorefrontLoader PHP class hooks into wp_enqueue_scripts.
  2. It checks: plugin enabled? Consent given? User not in excluded role?
  3. If all checks pass, it enqueues cp-storefront.min.js and cp-storefront.min.css.
  4. A cpConfig JavaScript object is injected via wp_localize_script containing active campaigns, settings, cart data, and page context.

Session Flow

  1. Session Init — On first page load, the script creates or resumes a session via the REST API. A session cookie (earlybirds_cp_session_id) persists the session ID.
  2. Event Collection — Behavior events (page views, scroll, idle, cart changes) are collected in memory.
  3. Batch Sending — Events are sent to the server in batches at the configured interval (default: every 5 seconds).
  4. Intent Scoring — The client-side intent scorer calculates a 0–100 score from 12 weighted signals.
  5. Trigger Evaluation — Active campaigns are evaluated against the current state (intent score, cart value, page type, device, etc.).
  6. Intervention Rendering — When a campaign matches, the intervention is rendered as a DOM overlay.
  7. Outcome Tracking — Impressions, dismissals, clicks, and spins are logged back to the server.

Consent Gating

If a supported consent plugin is detected, the storefront script waits for consent before initializing any tracking. Events fired before consent is given are discarded.

Page-Unload Safety

On page unload, any pending events are flushed using the navigator.sendBeacon API to ensure data is not lost.

27. Demo Data System

CartPulse AI automatically imports demo data on first activation so you can explore all features immediately without waiting for real traffic.

What Is Imported

Clearing Demo Data

Demo data can be cleared in two ways:

Clearing demo data removes all synthetic campaigns, analytics, and sessions. Real data is never affected.

28. Compatibility

WooCommerce HPOS

CartPulse AI declares full compatibility with WooCommerce High-Performance Order Storage (HPOS / Custom Order Tables). It uses WooCommerce order APIs that work with both legacy wp_posts storage and the new wc_orders tables.

Cache Plugins

CartPulse AI works with page caching plugins (WP Rocket, W3 Total Cache, LiteSpeed Cache, etc.). The storefront script uses the REST API for dynamic data, so cached pages do not interfere with session tracking or intervention delivery.

Tip: If using WP Rocket, exclude the /wp-json/earlybirds-cp/ path from caching. CartPulse AI will show a compatibility notice if WP Rocket is detected.

Multisite

CartPulse AI has not been tested with WordPress Multisite. Activate and configure it on a per-site basis only. Network activation is not supported.

Staging vs. Production

You can run CartPulse AI on both staging and production sites. Use separate API keys per site. To avoid polluting analytics, either disable campaigns on staging or use the Preview Mode toggle.

Theme Compatibility

Interventions render as overlay elements (z-index: 999999) that work with any standard WordPress/WooCommerce theme. Customization is available via design options in the campaign editor.

29. Troubleshooting

Interventions Not Appearing

  1. Confirm the campaign is set to Active and within its scheduled date range.
  2. Check that your user role is not in the Excluded Roles list (Administrator is excluded by default). Use Preview Mode to test as admin.
  3. Open browser DevTools console for JavaScript errors. Look for CP Debug HTML comments in the page source.
  4. Verify cookie consent — if your consent plugin hasn’t been accepted, tracking is blocked. Toggle Cookie Consent to “None” temporarily to isolate.
  5. Check that WooCommerce is active and the page is a WooCommerce page (product, cart, checkout, shop).
  6. Verify the trigger conditions: minimum intent score, minimum cart value, device type, page type.
  7. Check max interventions per session — if the visitor has already seen the maximum, no more will fire.
  8. Enable Debug Mode in Settings and check WooCommerce → Status → Logs for cartpulse-ai entries.

AI Content Not Generating

  1. Go to Settings → AI and click Test Connection. If it fails, your API key may be invalid or have insufficient credits.
  2. Check the monthly budget — if reached, AI is paused until the next billing cycle. The campaign uses its static fallback message.
  3. Verify the model name matches one available in your API account (e.g., gpt-4o requires OpenAI access).
  4. Check the log viewer in Tools for AI-related error messages.

Coupons Not Applying

  1. Verify the coupon exists in Marketing → Coupons.
  2. Check coupon expiry — the coupon may have already expired (configurable per campaign).
  3. Verify the discount type and amount are valid for the cart contents.
  4. Check WooCommerce coupon settings for minimum spend or product restrictions.

Analytics Not Updating

  1. Analytics are aggregated by an hourly cron job. Wait up to 60 minutes after a conversion.
  2. If data is still missing, run wp earlybirds status and verify WP-Cron is running.
  3. Check that the visitor’s session was not excluded by role, page, or consent settings.
  4. Verify the earlybirds_cp_aggregate_analytics cron event is scheduled (check Tools → System Status).

Database Migration Errors

  1. Verify your database user has CREATE TABLE privileges.
  2. Run wp earlybirds migrate via WP-CLI for detailed error output.
  3. Check the log viewer for migration-specific errors.
  4. If tables already exist partially, use Tools → Run Migrations (safe to re-run).

PHP Warning: sodium Extension Missing

API key encryption requires the sodium PHP extension (bundled with PHP 7.2+, enabled by default on most hosts).

REST API Errors (403/401)

  1. Ensure your WordPress REST API is not blocked by a security plugin (Wordfence, Sucuri, etc.).
  2. Check .htaccess rules that might block /wp-json/ requests.
  3. Verify the nonce is being sent correctly (check for caching plugins stripping nonces).

Storefront Script Not Loading

  1. Check the page source for <!-- CP Debug: ... --> comments that explain why the script was skipped.
  2. Verify that storefront/build/cp-storefront.min.js exists in the plugin directory.
  3. Check for JavaScript conflicts with other plugins by deactivating them one at a time.

Weekly Digest Not Sending

  1. Verify Weekly Digest is enabled in Settings → Notifications.
  2. Check that WP-Cron is running (wp cron event list).
  3. Verify the recipient email address is valid.
  4. Check your server’s mail logs or use an SMTP plugin for reliable email delivery.

Cart Recovery Emails Not Sending

  1. Verify Cart Recovery is enabled in Settings.
  2. Check the earlybirds_cp_send_recovery_emails cron event in Tools → System Status.
  3. Ensure email addresses are captured (visitors must provide their email at checkout or via email capture).
  4. Check server mail configuration and WP mail logs.

30. FAQ

Do I need an API key?

No. CartPulse AI works without an AI provider. Built-in templates use merge tags for personalization. Adding an AI provider (OpenAI or Anthropic) enhances interventions with dynamic, context-aware copy. You control costs via the monthly budget setting.

Where is data stored?

All data is stored in your WordPress database. Sessions, events, campaigns, and analytics never leave your server. Only the prompt content (cart summary, store context) is sent to the AI provider when AI content is requested.

Can I use my own coupon codes?

Yes. In the campaign’s static template, reference any existing WooCommerce coupon code. Alternatively, enable auto-generation to create unique coupons on the fly.

Does it work with HPOS?

Yes. CartPulse AI declares WooCommerce HPOS compatibility and uses order APIs that work with both legacy wp_posts storage and the new wc_orders tables.

How do I translate the plugin?

A .pot file is included in languages/. Use Poedit, Loco Translate, or a similar tool to create .po/.mo files. Place them in wp-content/languages/plugins/.

Which cookie consent plugins are supported?

Auto-detect mode supports: CookieYes, Complianz, Cookie Notice (dFactory), Borlabs Cookie, CookieBot, and WP Consent API. Tracking is gated until consent is given.

Does it slow down my store?

No. The storefront script is ~15 KB gzipped, loads asynchronously, and uses a beacon pattern for server communication. No impact on page load times or Core Web Vitals.

Can I run it on staging and production?

Yes. Use separate API keys per site, and verify your purchase where needed for updates and support. Disable campaigns or use Preview Mode on staging to avoid polluting analytics.

Does it work on WordPress Multisite?

CartPulse AI has not been tested with Multisite. Activate on a per-site basis only.

How does revenue attribution work?

When a visitor sees an intervention and later completes a purchase in the same session, the order revenue is attributed to that campaign. This happens automatically via the woocommerce_checkout_order_processed hook.

What happens when the AI budget is reached?

AI content generation pauses. Campaigns automatically fall back to their static template text (headline, body, CTA). Tracking and analytics continue normally.

Can I customize the intervention styles with CSS?

Yes. Interventions have well-structured CSS classes prefixed with cp-. You can add custom CSS in your theme’s Additional CSS or a child theme stylesheet.

How do I test campaigns without affecting real visitors?

Enable Preview Mode from the Dashboard. This shows interventions only to administrators while regular visitors continue to see normal behavior.

What data is included in the support bundle?

System status, plugin settings (API keys redacted), campaign configs, and the last 500 log lines. No visitor data or PII is included.

Can campaigns be cloned?

Use Export → Import to duplicate campaigns. Export creates a JSON file; import creates all campaigns as drafts that you can customize.

How is the intent score calculated?

The score combines 12 weighted signals: time on page, scroll depth, cart additions, checkout progress, page views, return visits, idle time, exit signals, tab switches, cart modifications, product views, and category browsing. Weights are configurable in Settings.

31. Changelog

Version 1.0.0 (March 2026)

32. Support & Credits

Getting Support

For support, please use the support channel linked in your CodeCanyon purchase confirmation. Include your support bundle (from Tools → Generate Support Bundle) for faster resolution.

Before Contacting Support

  1. Check the Troubleshooting section for common issues.
  2. Review the FAQ section.
  3. Enable Debug Mode and check the log viewer for error messages.
  4. Generate a support bundle from the Tools page.

Third-Party Credits

See THIRD_PARTY_LICENSES.md in the plugin folder for full third-party license text.

LibraryVersionLicenseUsage
Chart.js4.4.7MITAnalytics dashboard charts.

License

CartPulse AI is licensed under the GPL v2 or later. See the license.txt file included with the plugin for full license text.


CartPulse AI v1.0.0 — By Earlybirds — © 2026 All Rights Reserved.