Standard Setup (Free)

The core framework is available on the WordPress.org repository.

• Navigate to Plugins -> Add New.
• Search for CartLane.
• Install and activate the plugin.

WP-CLI

# 1. Install base plugin
wp plugin install cartlane --activate

# 2. Upload and activate Pro
wp plugin install ./cartlane-pro.zip --activate

Global Settings

Once installed, navigate to CartLane -> Settings in your WordPress dashboard. Here you can configure:

• Brand Colors: Sync your brand primary and secondary colors across all checkouts and carts.
• Typography: Inherit your theme font stack or define custom Google Fonts.
• HPOS Sync: Monitor high-performance order storage sync status directly from the panel.

Advanced Developer Hooks

Developers can extend supported behavior through the documented Hooks & Filters page. Settings writes should use the authenticated REST settings endpoint or the CartLane admin UI so sanitization, capability checks, and analytics cache invalidation still run.

Overview Cards

The dashboard summarizes store revenue, orders, checkout conversion, order bump activity, recovery signals, and module health using local WooCommerce and CartLane analytics data.

• Revenue and order cards use WooCommerce order state rather than browser-only events.
• Conversion cards compare checkout sessions, completed orders, bump impressions, accepted bumps, abandoned carts, and recovered carts where available.
• Dashboard numbers are intended for CartLane-assisted operational decisions, not as a replacement for your accounting reports.

System Status

Review enabled modules, WooCommerce compatibility, HPOS readiness, and recent plugin state before debugging cart or checkout behavior.

Recent Activity

Recent events help you confirm that cart, checkout, recovery, order bump, funnel, upsell, and Smart Offer activity is being recorded after setup changes.

Triggering the Cart

By default, CartLane automatically binds to your theme native Add to Cart buttons and cart menu icons. You can manually trigger the side cart using custom CSS classes.

• .cartlane-open-cart - Add this class to any link or button to open the side cart on click.
• .cartlane-toggle-cart - Toggles the side cart visibility dynamically.

JavaScript Custom Events

CartLane dispatches custom DOM events that you can listen to in your theme or custom scripts.

// Listen for when the side cart is fully opened
document.addEventListener( 'cartlane:cart_opened', function( e ) {
    console.log( 'Cart opened! Current total:', e.detail.cartTotal );
});

// Listen for an item being added to the cart
document.addEventListener( 'cartlane:item_added', function( e ) {
    console.log( 'Added product ID:', e.detail.productId );
});

Field Editor

CartLane provides a built-in field editor to hide, require, or rename checkout fields without writing custom PHP.

• Hide Company Name: Perfect for B2C stores.
• Hide Phone Number: Only ask for what you need to ship.
• Address workflow: Keep shipping and billing fields focused on the details your store actually needs.

Trust Signals

CartLane automatically injects security badges and trust signals around the Place Order button to reassure buyers right before they pay.

Global Placement

CartLane leverages React and Zustand for state management, meaning Order Bumps are not restricted to just the checkout page. You can dynamically render them inside the AJAX Side Cart as well.

Offer Setup

Create order bump offers from CartLane -> Order Bumps. Each offer should have a target product, clear headline, optional description, display status, and placement that matches the checkout or side cart moment where it should appear.

• Use product search to select the bump product or variation-backed product.
• Keep CTA, headline, product image, and checkbox behavior aligned so buyers can clearly opt in.
• Review bump accepted and bump paid metrics separately in Analytics to avoid over-counting intent as paid revenue.

Templates And Timers

Free stores can use the supported free templates and checkout color presets. Pro stores can unlock premium templates, custom content display order, and timer source controls where the active license permits them.

Live Cart Tracking

CartLane uses early-capture technology. As soon as a user enters an email address in the checkout field or logs into their account, cart state can be synchronized in the background and later reviewed in the Abandoned Cart workspace.

Email Testing

Use the Abandoned Cart screen to preview the recovery email payload and send a test message before enabling a production recovery workflow.

• Preview email output before changing templates or copy.
• Send a test message from wp-admin to confirm mail delivery behavior.
• Check spam, transactional email, and SMTP logs if test delivery fails.

Recovery Records

Captured carts can be reviewed, opened individually, resent where supported, and linked to recovered WooCommerce orders through CartLane analytics attribution.

Event Tracking

Through the Event_Tracker module, CartLane can record module-specific events locally without requiring third-party tracking scripts.

• Cart events: drawer opened, item added, coupon applied, checkout clicked.
• Order bump events: bump viewed, accepted, removed, and purchased.
• Funnel and upsell events: step viewed, offer accepted, offer skipped, and journey completed when Pro modules are active.
• Recovery events: cart captured, email queued, email sent, recovery clicked, and recovered checkout linked.
• Smart Offer events: recommendation impressions, clicks, and cart additions when Pro Smart Offers are active.

Report Views

Store owners can review CartLane reports by module and date range so operational decisions stay tied to plugin activity instead of mixed marketing data.

• Overview: revenue, orders, average order value, checkout conversion, module performance, and recent events.
• Events: filterable retained event history with pagination, event type filters, module filters, revenue filters, date filters, and CSV export.
• Event drawer: selected events can show context, journey, related objects, comparable sessions, and investigation signals where data exists.

Event Intelligence

Recent CartLane versions add bounded event context for session, journey, similar-session, related-object, investigation, and revenue analysis. This keeps event review useful without loading the entire analytics dataset into the browser.

Developer Hooks

For reporting integrations, use the Analytics Events screen export or the authenticated /analytics/events REST endpoint. CartLane records events through its internal Analytics_Recorder and exposes retained events through bounded, paginated reads.

Core Concepts

A CartLane Funnel is built using nodes connected via conditional paths.

• Trigger Nodes: What starts the funnel, such as Global Checkout or a specific product purchase.
• Offer Nodes: The pages shown to the user, such as Upsell or Downsell.
• Conditionals: Logic gates that route the user based on previous actions.

REST API Architecture

Funnel definitions are stored as serialized builder settings and managed through the authenticated /funnels REST endpoints. Every create, update, duplicate, and delete action requires Pro access and admin permission checks.

Offer Library

The Upsells workspace lists saved offers, summary metrics, gateway readiness signals, and offer setup guidance. Offers can be created, edited, duplicated, archived, and filtered by status or type.

• Use draft status while configuring a new post-purchase offer.
• Duplicate proven offers before testing copy, discount, template, or targeting changes.
• Archive offers that should no longer appear without deleting historical analytics context.

Offer Editor

Each offer can define the target product, discount behavior, display content, template, CTA and decline copy, rules, and optional downsell relationships where supported by the active configuration.

Runtime Sessions

CartLane Pro uses offer sessions for post-purchase view, accept, and decline actions. Runtime endpoints require a valid Pro entitlement and only authorize the current offer session.

Campaign Library

Smart Offers are managed as recommendation campaigns. Each campaign can be created, edited, duplicated, archived, filtered, and previewed before it appears in a storefront placement.

• Use active status only after product selection, placement, and rules are reviewed.
• Use archive instead of delete when you need to keep campaign history out of the active workspace.
• Use preview to confirm product matching before enabling a campaign.

Templates And Recipes

Offer templates and recipes help create common recommendation patterns such as cart add-ons, checkout add-ons, frequently bought together, and product-moment recommendations.

Placements

Supported placement logic can render recommendations in the Side Cart, Checkout, and product-page moments when the campaign rules and active Pro entitlement allow it.

Analytics

Smart Offer analytics can track impressions, clicks, cart additions, and campaign performance using CartLane local analytics events.

How It Works

Traffic is distributed across variants using a secure tracking cookie. The backend can record configured events and variant performance data for CartLane reports.

Developer API

A/B tests are managed through the authenticated /ab-tests REST endpoints. Use the testable-elements endpoint to discover supported targets and the winner endpoint to declare a selected variant.

Supported Rule Types

CartLane Pro supports a wide array of condition-based pricing architectures:

• Volume Discounts: Buy 5 to 9 items get 10% off; buy 10+ get 20% off.
• BOGO: Buy 2 t-shirts, get 1 cap free.
• Role-Based Pricing: Exclusive wholesale catalogs for logged-in B2B users.

Performance First

Traditional pricing plugins often crash WooCommerce due to recursive cart recalculations. CartLane rule engine evaluates pricing trees in memory and caches the outcome.

Programmatic Reporting

Developers can observe applied pricing rules for internal reporting without changing CartLane pricing calculations.

add_action( 'cartlane_pricing_rule_applied', function( $rule, $cart_item, $new_price, $original_price ) {
    error_log( sprintf( 'CartLane pricing changed %s to %s', wc_format_decimal( $original_price ), wc_format_decimal( $new_price ) ) );
}, 10, 4 );

Free Compatibility View

CartLane Free can expose compatibility and connection terminology so stores understand which gateway or integration paths need attention. Write operations and credential management remain gated by Pro access.

• Use the Free view to identify integration readiness before buying or activating Pro.
• Credential values are never displayed as raw secrets in the admin UI.
• Pro-only writes require the active CartLane Pro entitlement and REST permission checks.

Provider Credentials

CartLane Pro supports provider credential workflows for supported payment integrations such as Stripe and PayPal. Use matching test/live keys for the selected store mode.

• Save provider keys from the Integrations credentials drawer.
• Use test mode credentials while validating checkout and upsell flows on staging.
• Switch to live credentials only after checkout, order creation, and readiness tests pass.

Gateway Tests

Run gateway tests after saving credentials to confirm provider configuration, API reachability, test/live mode alignment, and adapter availability.

Supported Gateways

• Stripe: Adapter-readiness guidance for WooCommerce Stripe gateway integrations.
• PayPal: Adapter-readiness guidance for PayPal gateway workflows that support tokenized follow-up charges.
• WooPayments: Adapter-readiness guidance for WooPayments-based checkout flows.

Custom Gateway Integration

If you are using a local or custom payment gateway, return a RealUpsellGatewayAdapterInterface implementation through the gateway adapter filter.

add_filter( 'cartlane_upsell_real_gateway_adapter', function( $adapter, $provider, $readiness, $context ) {
    if ( 'my_gateway' !== ( $context['gateway_id'] ?? '' ) ) {
        return $adapter;
    }

    return new My_Custom_Upsell_Gateway_Adapter( $readiness, $context );
}, 10, 4 );

Free Endpoints

Pro Endpoints

Authentication (Nonce)

For logged-in users or sessions managed by WooCommerce, include the WordPress nonce in the headers of your requests.

fetch( '/wp-json/cartlane/v1/cart/update-item', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        'X-WP-Nonce': cartlane_data.nonce
    },
    body: JSON.stringify( { cart_item_key: 'abc123', quantity: 2 } )
} )
.then( res => res.json() )
.then( data => console.log( data ) );

Data Retrieval Methods

If you are writing custom integrations, always use WooCommerce CRUD objects to interact with orders created through CartLane.

// Correct way to get CartLane metadata from an HPOS order
$order = wc_get_order( $order_id );
$funnel_id = absint( $order->get_meta( '_cartlane_funnel_id' ) );
$funnel_step = absint( $order->get_meta( '_cartlane_funnel_step' ) );

// Avoid direct post meta reads for HPOS compatibility.
// $funnel_id = get_post_meta( $order_id, '_cartlane_funnel_id', true );

Analytics & HPOS

Our internal Analytics engine uses custom lightweight tables joined correctly with WooCommerce order tables using abstract DB query layers. No direct table hardcoding exists.

General Questions

CartLane is built for WooCommerce stores that want faster cart interactions, cleaner checkout controls, order bump workflows, and Pro funnel features.

• Does CartLane replace WooCommerce? No. CartLane extends WooCommerce cart and checkout workflows.
• Can I use only the side cart? Yes. Modules can be configured independently where the plugin settings expose module controls.
• Does CartLane require a page builder? No. CartLane works through plugin modules, WordPress hooks, and WooCommerce integration points.

Free vs Pro

The free plugin includes the core CartLane admin workspace and day-to-day cart, checkout, order bump, recovery, analytics, settings, and product search workflows. Pro unlocks advanced revenue automation and write-enabled premium modules.

• Free: Dashboard, Analytics, AJAX Side Cart, Checkout controls, Order Bumps, Abandoned Cart Recovery, Settings, product search, and read-only integration guidance.
• Pro: Funnel Builder, Post-Purchase Upsells, Smart Offers, A/B Testing, Dynamic Pricing, write-enabled Integrations, gateway readiness, Pro product search, license activation, and automatic update entitlement.
• License-gated features remain disabled until a valid Pro license is activated.

Compatibility

CartLane is designed for modern WooCommerce environments using current WordPress standards, REST endpoints, nonces, and HPOS-safe order access.

• PHP 8.0+ is recommended for production stores.
• WooCommerce HPOS is supported through WooCommerce CRUD APIs.
• Theme conflicts are usually resolved by checking cart trigger selectors and checkout template overrides.

Cart Issues

If the side cart does not open, confirm the module is enabled and your theme buttons are still using WooCommerce add-to-cart behavior.

• Clear page cache and object cache after changing CartLane module settings.
• Check that custom buttons include a supported CartLane trigger class or WooCommerce add-to-cart attributes.
• Disable script optimization temporarily if a performance plugin delays CartLane frontend assets.

Checkout Issues

Checkout conflicts usually come from theme template overrides, payment gateway scripts, or custom snippets changing WooCommerce fields late in the request.

• Test with a default WooCommerce-compatible theme to isolate template overrides.
• Confirm active payment gateways render correctly on the default WooCommerce checkout.
• Review custom snippets that modify checkout fields, totals, fees, or payment fragments.

Debug Checklist

When reporting an issue, capture the module state and environment first. This avoids guessing and shortens support turnaround.

1. WordPress version
2. WooCommerce version
3. CartLane version
4. Active theme name
5. Enabled CartLane modules
6. Browser console errors
7. Steps to reproduce

License Refresh And Deactivation

The Pro license screen can read the current entitlement, activate a new license, deactivate the current installation, and refresh signed entitlement state used by Pro module access and automatic update checks.

• Use refresh after renewing, changing, or troubleshooting an entitlement.
• Use deactivate before moving a license to another production installation.
• Do not share raw license keys or purchase codes in support tickets unless a secure support process explicitly requests them.

Safe Updates

For production WooCommerce stores, update Free and Pro together during low-traffic windows. Test dashboard loading, cart, checkout, order bump, recovery, Pro module, license, and payment-gateway flows immediately after the update.

• Back up the database before updating revenue-critical checkout tools.
• Update WooCommerce-compatible payment gateways before testing one-click upsell flows.
• Purge cache after updating CartLane assets or checkout configuration.

Before Contacting Support

Run through the troubleshooting checklist first and confirm the issue still occurs with CartLane enabled and relevant modules configured.

• Confirm the issue is reproducible on a clean browser session.
• Check browser console errors on the affected cart or checkout page.
• Test with cache/minification disabled if assets appear stale.

What To Include

Support requests should include exact steps, environment details, and the CartLane module involved.

• CartLane version, WordPress version, WooCommerce version, PHP version.
• Active theme and relevant checkout/payment/cart plugins.
• Screenshots or a short screen recording of the issue.
• Temporary admin access only when requested through the official support workflow.