Customize abandoned cart recovery with code

CheckoutWC’s abandoned cart recovery tracks carts once a customer enters a valid email address at checkout, then sends your recovery emails if they leave without ordering. This page covers the hooks for changing that with code.

These snippets were checked against the CheckoutWC 11.5.0 code. Test them on a staging site first.

Where to add these snippets

Add PHP snippets under CheckoutWC » Advanced » Scripts, in the PHP Snippets box, or in a child theme’s functions.php or a code snippets plugin. The PHP Snippets box runs on storefront requests, not in the WordPress admin. A snippet that must also run in the admin goes in the child theme or a code snippets plugin.

How cart recovery works

  1. Tracking. When a customer enters a valid billing email on the CheckoutWC checkout, CheckoutWC saves their cart, name, email, subtotal and checkout fields. It updates the saved cart each time the checkout refreshes.
  2. Abandonment. Every 5 minutes, an Action Scheduler task (cfw_acr_check_carts) marks carts older than Cart Is Abandoned After X Minutes as abandoned and schedules the first email.
  3. Emails. Each published recovery email is sent at its own delay, through the Action Scheduler task cfw_acr_send_email.
  4. Recovered or lost. If the customer orders and the order reaches one of your Cart Recovered Order Statuses, the cart is marked recovered. 30 days after the last email, an unrecovered cart is marked lost (cfw_acr_mark_lost).

These tasks depend on WordPress cron. See Make sure WordPress cron is working.

Choose which carts are tracked

Before writing code, check the settings under CheckoutWC » Cart Recovery: Exclude From Abandoned Cart Recovery By Role excludes customers by their user role.

Exclude carts with cfw_acr_exclude_cart

The cfw_acr_exclude_cart filter runs each time CheckoutWC is about to save a cart. Return true to skip tracking it.

Parameter Type Description
$exclude bool Whether to skip this cart. Default false.
$email string The customer’s email address.
$cart_contents array The cart contents.
$subtotal float The cart subtotal, before tax.
$first_name string The customer’s first name.
$last_name string The customer’s last name.
$fields array The checkout field values.
$meta array Extra data from cfw_acr_cart_meta.

The filter runs on every checkout refresh, so a cart that starts below a threshold is tracked once it rises above it.

Skip carts under $50:

add_filter( 'cfw_acr_exclude_cart', function ( $exclude, $email, $cart_contents, $subtotal ) {
    return $subtotal < 50 ? true : $exclude;
}, 10, 4 );

Skip staff and test addresses:

add_filter( 'cfw_acr_exclude_cart', function ( $exclude, $email ) {
    if ( false !== strpos( $email, '@yourcompany.com' ) || in_array( $email, array( '[email protected]' ), true ) ) {
        return true;
    }
    return $exclude;
}, 10, 2 );

Skip customers who ordered in the last 14 days:

add_filter( 'cfw_acr_exclude_cart', function ( $exclude, $email ) {
    $recent = wc_get_orders( array(
        'customer'   => $email,
        'date_after' => '14 days ago',
        'status'     => array( 'completed', 'processing' ),
        'limit'      => 1,
    ) );
    return empty( $recent ) ? $exclude : true;
}, 10, 2 );

Track carts with no recovery email published

By default, CheckoutWC only tracks carts while at least one recovery email is published, or while Disable Email Sending is on. To track carts with no email published, for example to build up the report first:

add_filter( 'cfw_acr_track_cart_without_emails', '__return_true' );

A cart is still only tracked once the customer enters an email address.

Store extra data with a cart

The cfw_acr_cart_meta filter adds your own data to each tracked cart. It starts with an empty array each time. The data is saved with the cart’s checkout fields. It isn’t available as a merge tag, so use it in your own reports or code.

The filter runs during the checkout’s background update request, not the page the customer arrived on, so URL parameters and the referrer aren’t available there. To record UTM parameters, save them in a cookie when the visitor arrives, then read the cookie:

add_action( 'init', function () {
    if ( is_admin() || headers_sent() ) {
        return;
    }
    foreach ( array( 'utm_source', 'utm_medium', 'utm_campaign' ) as $key ) {
        if ( ! empty( $_GET[ $key ] ) ) {
            setcookie( 'my_' . $key, sanitize_text_field( wp_unslash( $_GET[ $key ] ) ), time() + 30 * DAY_IN_SECONDS, COOKIEPATH, COOKIE_DOMAIN, is_ssl(), true );
        }
    }
} );

add_filter( 'cfw_acr_cart_meta', function ( $meta ) {
    foreach ( array( 'utm_source', 'utm_medium', 'utm_campaign' ) as $key ) {
        if ( ! empty( $_COOKIE[ 'my_' . $key ] ) ) {
            $meta[ $key ] = sanitize_text_field( wp_unslash( $_COOKIE[ 'my_' . $key ] ) );
        }
    }
    return $meta;
} );

Change recipients and email headers

Send to a different address

cfw_acr_send_to_email changes who receives a recovery email. It receives the customer’s address, the cart (a row from the carts table) and the recovery email’s post ID:

add_filter( 'cfw_acr_send_to_email', function ( $send_to, $cart, $email_id ) {
    // Example: send every recovery email to a test inbox on staging.
    if ( 'staging' === wp_get_environment_type() ) {
        return '[email protected]';
    }
    return $send_to;
}, 10, 3 );

Change the email headers

cfw_acr_email_headers filters the headers array, which holds the From, Reply-To and Content-Type headers built from your Cart Recovery settings. To change the reply address, use the Reply-To Address setting. To replace the Reply-To in code, remove the existing one first, so the email doesn’t have two:

add_filter( 'cfw_acr_email_headers', function ( $headers ) {
    $headers   = array_values( array_filter( $headers, function ( $header ) {
        return 0 !== stripos( $header, 'Reply-To:' );
    } ) );
    $headers[] = 'Reply-To: [email protected]';
    return $headers;
} );

Style recovery emails

cfw_acr_email_custom_css adds CSS after CheckoutWC’s own email styles. CheckoutWC moves the CSS inline before sending, so it works in most email clients.

add_filter( 'cfw_acr_email_custom_css', function ( $css ) {
    return $css . '
        .container { max-width: 640px; }
        #cfw_acr_cart_products_table img { border-radius: 8px; }
        #cfw_acr_cart_products_table td { padding: 12px 8px; }
    ';
} );
Selector What it styles
.body The email background
.container The centered content column (580px wide by default)
.main The white content area
.content-block Content sections
.footer The footer, including the automatic unsubscribe link
#cfw_acr_cart_products_table The cart products table from {{cart_products_table}}
.preheader The hidden preview text

The {{checkout_button}} button has its own inline styles. Change its label with {{checkout_button label="Finish your order"}}.

The older cfw_cart_table_styles filter takes an array, not CSS. Its style key has been deprecated since 10.1.0, so use cfw_acr_email_custom_css instead.

If Use WooCommerce Email Template is on for an email, it’s wrapped in WooCommerce’s email header and footer, so WooCommerce’s email styles apply as well.

Change email content

Write and edit recovery emails under CheckoutWC » Cart Recovery, in the WordPress editor. These merge tags are replaced when each email is sent:

Merge tag Replaced with
{{site_name}} Your site title
{{site_url}} Your site address
{{cart_products_table}} A table of the cart’s products
{{checkout_url}} A link that restores the cart and opens the checkout
{{checkout_button}} A button with that link. Add label="…" to change its text; the default is “Complete Order”
{{customer_email}} The customer’s email address
{{customer_firstname}} The customer’s first name, or “there” if it’s empty
{{customer_lastname}} The customer’s last name
{{customer_full_name}} The customer’s full name
{{cart_abandoned_date}} The date the cart was created
{{unsubscribe_url}} A link that unsubscribes the customer from recovery emails

If an email doesn’t include {{unsubscribe_url}}, CheckoutWC adds an unsubscribe link at the end.

Links back to your store already carry UTM parameters: utm_source=CheckoutWC_ACR, utm_medium=email, utm_campaign=abandoned_cart, and utm_term set to the recovery email’s ID. Your analytics can show which email in the sequence brought customers back, without code.

There’s no filter for the finished email’s HTML. Older versions of this page described a cfw_acr_email_content filter, which doesn’t exist in CheckoutWC. To change the final HTML, for example to add a tracking pixel, mark recovery emails with a header and change them in WordPress’s wp_mail filter:

add_filter( 'cfw_acr_email_headers', function ( $headers ) {
    $headers[] = 'X-CFW-ACR: 1';
    return $headers;
} );

add_filter( 'wp_mail', function ( $args ) {
    $headers = is_array( $args['headers'] ) ? implode( "\n", $args['headers'] ) : (string) $args['headers'];
    if ( false === strpos( $headers, 'X-CFW-ACR: 1' ) ) {
        return $args;
    }
    $pixel           = '<img src="https://example.com/open.gif" width="1" height="1" alt="" />';
    $args['message'] = str_replace( '</body>', $pixel . '</body>', $args['message'] );
    return $args;
} );

Run code on recovery events

Hook Type When it runs
cfw_acr_send_email Action, with $cart_id and $email_id When a scheduled recovery email is processed. Callbacks at the default priority run after CheckoutWC has sent the email.
cfw_acr_mark_lost Action, with $cart_id When an unrecovered cart is marked lost, 30 days after the last email.
cfw_unsubscribe_successful_message Filter, with the message The text shown after a customer unsubscribes. Default “You have been unsubscribed from our cart reminder emails.” It’s shown as plain text.
add_action( 'cfw_acr_send_email', function ( $cart_id, $email_id ) {
    // Your code: for example, log the send to your CRM.
}, 10, 2 );

add_filter( 'cfw_unsubscribe_successful_message', function () {
    return 'You won\'t receive any more reminders about this cart.';
} );

cfw_checkout_update_order_review runs on every checkout refresh, whether or not a cart is tracked, so it isn’t a reliable signal that a cart was saved.

Query tracked carts

Tracked carts are stored in the {prefix}cfw_acr_carts table, for example wp_cfw_acr_carts. The useful columns are:

Column Contents
id The cart’s ID
email, first_name, last_name The customer’s details
cart The cart contents, as JSON
fields The checkout field values and your cfw_acr_cart_meta data, as JSON
subtotal The cart subtotal
status new, abandoned, ineligible, recovered, lost or unsubscribed
wp_user The customer’s user ID, or 0 for guests
created When the cart was first tracked, in the database server’s time zone
emails_sent How many recovery emails have been sent

ineligible means CheckoutWC won’t email the cart: it was abandoned while no recovery email was published, or its email address is invalid. For example, to count carts recovered in the last 30 days:

global $wpdb;
$table     = $wpdb->prefix . 'cfw_acr_carts';
$recovered = (int) $wpdb->get_var( $wpdb->prepare(
    "SELECT COUNT(*) FROM {$table} WHERE status = %s AND created >= %s",
    'recovered',
    date( 'Y-m-d H:i:s', strtotime( '-30 days', current_time( 'timestamp' ) ) )
) );

The table holds customers’ personal details, so treat any export of it accordingly.

Common issues

My filter doesn’t run

Check where the snippet lives. Code in the PHP Snippets box runs on storefront requests only, so it won’t affect anything that happens in the WordPress admin. Move it to a child theme’s functions.php or a code snippets plugin if it needs to run there.

Recovery emails never send

Cart recovery runs on WordPress cron. See Make sure WordPress cron is working.

Keep learning