CMLS – Customer Match List for Google Ads & Meta Ads

Build Google Ads customer lists (Customer Match) from your WooCommerce orders: one CSV file per billing country, updated automatically on a schedule. Each country file has its own private, tokenized URL that Google Ads fetches straight from your WordPress site, with no third-party connector or API key — ideal for marketing teams that run per-country campaigns and want clean, single-market audience lists.

The values are hashed with the same SHA-256 normalization used by both Google Ads Customer Match and Meta Ads Custom Audiences, so the same file can also be uploaded manually to Meta Ads Manager (see FAQ).

Why this export?
Not all purchases are captured by Google Ads tracking; periodic uploads of Customer Match lists help targeting and campaign performance. Even Google’s automatic conversion-based customer lists (auto-enabled for eligible accounts from August 2026) only contain tag-tracked conversions — this plugin exports from the order database itself, so ad-blocked, phone, offline and historical orders are included too (see FAQ). The export reflects your order database as-is — applying your store’s consent choices and legal requirements to it is your responsibility as the merchant (see the GDPR / privacy FAQ).

Why per-country files?
Marketing teams optimize Google Ads campaigns per country. Mixing a German audience into a Romanian campaign’s match list pollutes the targeting. This plugin keeps each market in its own file.

How it works

1. You pick an audience window (all orders, the last 365 or 540 days, or any number of days) and the order statuses that count as a purchase.
2. Every night the plugin rebuilds one CSV per billing country from the orders inside the window, hashing the customer fields. The new files replace the old ones in one step, so customers who stopped buying drop out and Google never fetches a half-written file. Feed URLs never change.
3. Between rebuilds, a scheduled job (1, 6, 12, or 24 hours) appends new orders to the right country file. Orders that reach a selected status late (delayed payment confirmation, manual completion) are appended the moment they do, so they are never missed.
4. Each country file is downloadable from a secret URL that you hand to your marketing team. They paste it into Google Ads Data Manager → HTTPS connector as a customer list, and Google fetches the latest version on its own schedule. A one-time manual upload works too.
5. Optionally, value segments add extra files with only some of your customers, such as your top 10% by spend or big spenders who stopped buying, each with its own URL.

Features

• Per-country splitting — one CSV per ISO billing country, never mixed.
• Optional all-countries file — one more URL with every country together, for a campaign that targets them all.
• Audience window with a nightly rebuild — keep only customers who ordered in the last N days. The rebuild runs in the background and swaps the new files in at once; URLs stay the same.
• Any order status counts — pick Completed, Processing, or any custom status added by another plugin, in one searchable list.
• Value segments — up to 5 extra lists built from each customer’s spend, order count and last order date (top X% by spend, a minimum spend, repeat buyers, lapsed customers). Multi-currency stores can leave other currencies out or convert them at their own rates.
• Health tab — checks the schedule, the last file write, the storage folder, the nightly rebuild and your permalinks, and counts the rows in every file against what it should hold.
• Background backfill and rebuild from the admin (no CLI needed) — runs via Action Scheduler.
• One-time backfill via WP-CLI with status filter, date filter (--days=N, --since, --until), dry-run, and batch-size control.
• Scheduled incremental appends every 1, 6, 12, or 24 hours between rebuilds.
• Per-(email, country) deduplication via a dedicated indexed database table — no full-file scans, single indexed insert per row.
• CSV column headers: Email, Phone, First Name, Last Name, Country, Zip.
• Hashed per Google spec: SHA-256 of trimmed/lowercased values, phone normalized to E.164 with the leading + — the same hashing Meta Ads Custom Audiences accept.
• Secret tokenized URLs — one per country, all resettable from the admin or via CLI.
• Storage hardening — files live under wp-content/uploads/customer-match-list-google-ads/ with filenames containing a 64-bit hash derived from the token, behind a deny-all .htaccess on Apache.
• REST endpoint stream — the CSV is sent chunked with nocache_headers().
• HPOS-first SQL — direct JOIN on wc_orders + wc_order_addresses (or posts+postmeta on classic). Designed for stores with tens of millions of orders.

Admin Dashboard Settings

WooCommerce → Marketing → Customer Match List.

From there you can:

• Feeds: see per-country status (row count, file size, and the tokenized URL ready to copy) and the value segment URLs.
• Settings: pick the update interval (1/6/12/24 h), the audience window, the order statuses and whether to offer an all-countries file.
• Value segments: switch segments on, choose how spend is counted, and add up to 5 segments from templates (VIP, High value, Valuable, Lapsed high value, Repeat buyers) or your own rules.
• Health: a check list (schedule, last write, storage folder, directory listing, nightly rebuild, permalinks, list sizes) and every file’s row count next to what it should hold, with a one-click rebuild when they differ.
• Tools: run the update now, rebuild now, start a background backfill and watch its progress, reset the token (regenerates every URL, renames every file), or delete every file and reset the dedup table.
• An automated check confirms the webserver does not expose the CSV directory via a public file listing.

WP-CLI

• wp cmls rebuild (or wp cmls rebuild-now) — rebuilds every file from the orders inside the audience window and swaps them in, in the same process (no PHP time limit). Same result as the nightly rebuild and Tools → Rebuild now.
• wp cmls backfill — one-time backfill of historical orders, split by country. Flags: --statuses=processing,completed (defaults to the statuses saved in the settings), --all-statuses, --days=N, --since=YYYY-MM-DD, --until=YYYY-MM-DD, --dry-run, --batch-size=5000, --force. The next rebuild goes back to the saved window and statuses.
• wp cmls update-now (or wp cmls run-now) — appends orders placed since the last run, right away. Same code path as the scheduled cron and Tools → Update now.
• wp cmls status — prints a table with one row per country (row count, file size, URL) and the all-countries URL when it’s on, then the audience window, statuses and rebuild times.
• wp cmls reset-token — regenerates the token and renames every file to match. If a file can’t be renamed, nothing changes and the command fails.
• wp cmls delete-file — deletes every country CSV and truncates the dedup table.