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
- 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.
- 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. - Emails. Each published recovery email is sent at its own delay, through the Action Scheduler task
cfw_acr_send_email. - 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.