Title: CMLS – Customer Match List for Google Ads & Meta Ads Author: Eduard Doloc Published: جولای 14, 2026 Last modified: اکتبر 15, 2026 --- Search plugins ![](https://ps.w.org/customer-match-list-google-ads/assets/banner-772x250.png?rev =3609357) ![](https://ps.w.org/customer-match-list-google-ads/assets/icon.svg?rev=3609357) # CMLS – Customer Match List for Google Ads & Meta Ads By [Eduard Doloc](https://profiles.wordpress.org/rwky/) [Download](https://downloads.wordpress.org/plugin/customer-match-list-google-ads.2.0.0.zip) * [Details](https://haz.wordpress.org/plugins/customer-match-list-google-ads/#description) * [Reviews](https://haz.wordpress.org/plugins/customer-match-list-google-ads/#reviews) * [Installation](https://haz.wordpress.org/plugins/customer-match-list-google-ads/#installation) * [Development](https://haz.wordpress.org/plugins/customer-match-list-google-ads/#developers) [Support](https://wordpress.org/support/plugin/customer-match-list-google-ads/) ## Description Build **Google Ads Customer Match lists** from your **WooCommerce** orders: one CSV file per billing country, updated automatically on a schedule. Each country file is downloadable via a private and secure (tokenized) URL — 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 can paste it into **Google Ads Data Manager HTTPS connector** and Google fetches the latest list on its schedule OR do one-time manual upload. 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. * **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. * **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 exported columns 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. * **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 and the order statuses. * **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. * **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` — 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. * `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 run-now` — runs the incremental writer immediately (same code path as the scheduled cron). * `wp cmls status` — prints a table with one row per country (row count, file size, URL), then the audience window, statuses and rebuild times. * `wp cmls reset-token` — regenerates the token and renames every country file to match. * `wp cmls delete-file` — deletes every country CSV and truncates the dedup table. ## Screenshots [⌊The admin page under WooCommerce - Marketing, showing the schedule selector, per- country URL table, and backfill controls.⌉⌊The admin page under WooCommerce - Marketing, showing the schedule selector, per-country URL table, and backfill controls.⌉[ The admin page under WooCommerce – Marketing, showing the schedule selector, per- country URL table, and backfill controls. ## Installation 1. Upload the plugin folder to `wp-content/plugins/customer-match-list-google-ads`( or install from the WordPress.org repository). 2. Activate **CMLS – Customer Match List for Google Ads & Meta Ads**. WooCommerce must already be active. 3. Go to **WooCommerce Marketing Customer Match List**. 4. On the **Settings** tab, pick the update interval (1, 6, 12, or 24 hours), the audience window (new installs start at 540 days) and the order statuses. 5. Build the files: 6. * **From the admin** — click **Rebuild now** on the **Tools** tab, or wait for the nightly rebuild. You can close the tab; it keeps running. * **From the shell** — `wp cmls rebuild`. 7. When the rebuild finishes, the **Feeds** tab shows one URL per country. Copy each URL and paste it into Google Ads Data Manager HTTPS connector for the corresponding country’s Customer Match list. ## FAQ ### Why one file per country? Marketing teams optimize Google Ads campaigns per country. Mixing audiences degrades match-rate signals and wastes budget on irrelevant impressions. Each country file is independent and can be wired into its own Customer Match list. Google’s Data Manager pulls each URL on its own schedule, so you can refresh some markets without affecting others. ### How do I plug a URL into Google Ads? In Google Ads **Tools and Settings** **Audience Manager** **Your data sources**, set up a **Customer Match** audience and choose the **HTTPS** data source. Paste the country-specific URL from the plugin’s admin page. Google Ads fetches the file on its own cadence; our plugin keeps the file fresh per the schedule you picked. ### Google says it’s turning on “conversion-based customer lists” — do I still need this plugin? Yes — they complement each other. In 2026 Google began automatically enrolling accounts that use both Enhanced Conversions and Customer Match into **conversion-based customer lists** (enrollment emails went out from June 2026; data processing starts August 18, 2026). Those lists are built solely from what the Google Ads tag captures on your site from that point on: customers using ad blockers or declining your consent banner never enter them, and neither do phone, imported, or historical orders. This plugin builds Customer Match lists from the **WooCommerce order database** instead — every completed order, including full order history via backfill, split into one file per country, with a mailing-address fallback when an order has no email or phone. Keep both: attach the automatic conversion-based lists and the per- country lists this plugin feeds, and Google deduplicates matched customers on its side. ### Does the file work with Meta (Facebook) Ads? Yes. Meta Ads Custom Audiences use the same SHA-256 hashing of normalized (trimmed, lowercased) values, so a country CSV can be uploaded to Meta Ads Manager as a customer list — map the columns in Meta’s upload screen. Note that Meta does not pull files from URLs; the pull-from-URL workflow is Google-specific, so on Meta use manual upload. ### How long does the backfill take? Roughly 10 seconds per 150,000–200,000 orders on typical hardware. The query path is direct SQL against `wc_orders` + `wc_order_addresses` (HPOS). For 1M+ orders the CLI is still the most reliable option because no PHP/web timeout applies; the admin Action-Scheduler-backed runner also handles 1M+ but each batch must complete within the host’s PHP limit and if it does not then it won’t finish. ### What happens to orders with no billing country? In theory it’s impossible as billing and shipping is country based; but in case this ever happens they are skipped. There is no correct file to route them to, and Google’s per-country Customer Match campaigns can’t use them anyway. The same applies to orders with an invalid country code. ### What about orders with no email? They get written. Google Customer Match accepts a row with **any one** of: email, phone, or full mailing address (first name + last name + zip). The plugin includes a row as long as one of those identifiers is present alongside a valid country. Deduplication is still single-column: it uses email when available, otherwise phone, otherwise the mailing address. Google handles cross-identifier deduplication on its side after matching to a Google account — so a customer who orders once with email + phone and again with only their phone will appear as two rows in the CSV but as one user in your Customer Match audience. ### Will the same customer appear in multiple country files? Yes — but only if they actually ordered from multiple countries! ### I ran the backfill twice — why didn’t it write more rows the second time? This is by design, as every `(email, country)` pair is recorded the first time it’s seen and never re-written. To regenerate everything from scratch (for example after toggling debug mode), click** Tools Rebuild now** or run `wp cmls rebuild`. The rebuild starts from empty files and swaps them in when it’s done; the URLs stay the same. ### I get a 401 “REST API has been restricted to authenticated users” when I open the URL Some security plugins (“Admin and Site Enhancements” / ASE has this option, Disable REST API, etc.) block all unauthenticated REST traffic. This plugin does **not** attempt to override those policies — that would be hostile to the security setting you deliberately chose. If you hit this error, whitelist the plugin’s feed prefix in your security plugin’s exclusion list: `/wp-json/cmls/v1/feed/`. Google Ads (and any other configured consumer) needs unauthenticated GET access to that prefix — the tokenized URL is the sole authentication mechanism. ### Phone numbers — how reliable is the normalization without libphonenumber? For most countries (RO, DE, UK, FR, ES, US, NL, BE, PT, IT mobile, …) it’s correct. The routine accepts `+`, `00`, the country’s national trunk `0`, and bare national numbers (using the order’s billing country to fill in the dialing code). There is a known limitation for **Italian landlines**: in Italy the leading `0` is part of the national number, not a trunk prefix, so the routine may strip a digit it shouldn’t. Italian mobile numbers (3xx) are fine. **If you need strict accuracy across all locales, swap `CMLS_Writer::normalize_phone()` for a libphonenumber-based implementation.** ### Is WP-Cron reliable enough for the incremental updates? WordPress’s built-in cron is request-triggered: it only fires if someone hits the site. On low-traffic stores it may drift. For predictable runs, configure a real system cron that calls `wp-cron.php` every minute — standard WordPress practice and recommendation. ### Can I disable hashing for debugging? Yes. use the integrated define `CMLS_DISABLE_HASHING` in `wp-config.php`: ``` define( 'CMLS_DISABLE_HASHING', true ); ``` ### Does this support High-Performance Order Storage (HPOS) / Legacy Postmeta? Yes. The plugin declares `custom_order_tables` compatibility and queries `wc_orders` + `wc_order_addresses` directly when HPOS is enabled. On classic (postmeta) storage it falls back to `wp_posts` + `wp_postmeta` with a single conditional-aggregation query per batch. ### Does the plugin send any data outside my server? The plugin makes **no requests to third-party services** — no analytics, no tracking pixels, no telemetry. All processing happens on your WordPress install. (The directory- listing safety check is a one-second request from your server to its own uploads URL — see the directory-listing FAQ.) However, the whole point of the workflow is that **Google Ads (or any other consumer you configure) will pull the CSV from your site** at the tokenized URL. Anyone in possession of that URL can retrieve a file containing: * SHA-256 hashes of the customer’s email, phone, first name, and last name; * the customer’s billing country and postal code in plaintext. A value segment URL also shows that each customer in it belongs to that spend group( for example your top 10% by spend). Treat the tokenized URLs as secrets. If one leaks, use **Reset Token** in the admin( or `wp cmls reset-token`) to invalidate all existing URLs and rename the files on disk. See the site’s Privacy Policy page — this plugin registers suggested policy text via WordPress’s Privacy tool. ### Where are the files stored? wp-content/uploads/customer-match-list-google-ads/customer-match-{hash}-{country}. csv, and `customer-match-{hash}-seg-{id}.csv` for value segments. During a rebuild the new files are written next to them with a `.build` suffix. The `{hash}` is a 16-character hex derived from the secret token, so filenames are not guessable. An `index.php` placeholder in the directory prevents listing if your host happens to have it enabled and then it notifies the shop owner (when visiting the dashboard). ### What about directory listing? The settings page does a one-second loopback HTTP request to the uploads directory URL (`/wp-content/uploads/customer-match-list-google-ads/`) when you open it, caches the result for an hour, and shows one of three banners: * **Green — safe.** The server returned 200/401/403/404 with no listing markers( typically because the bundled `index.php` silence file is served, or because the webserver explicitly blocks directory listings). * **Red — exposed.** The server returned 200 with `Index of …` or with our CSV filename prefix in the body. Anyone who guesses the directory URL can enumerate your country files. Fix it: Apache `Options -Indexes` (or rely on the WordPress- shipped `.htaccess`); nginx `autoindex off;` in the relevant `location` block. * **Yellow — could not verify.** The loopback request failed within the one-second budget (NAT / split-DNS / firewall blocking PHP self-calls). Open the URL shown in the notice in a private/incognito browser window — if you see a listing, restrict it; otherwise you’re fine. The check is cached for an hour and re-runs immediately if you click **Re-check now**. ### What about Google’s 540-day lookback window? Google Ads keeps a Customer Match member for up to 540 days after that member was last uploaded or refreshed. Every time Google fetches your file, everyone in it is uploaded again, so a customer stays in the audience for as long as they are in the file, however old their orders are. That’s what the **audience window** (Settings tab) is for. Every night the files are rebuilt from the orders inside the window, so a customer whose last order is older drops out of the file. Google then stops refreshing them, and they leave the audience at the latest 540 days after the last fetch that included them. New installs start at 540 days; pick “All orders” to keep everyone. The backfill date range only limits the initial history import; the audience window is what keeps the list trimmed afterwards. Sites upgraded from 1.x keep their current files, which only ever grow, until the settings are saved once. Saving turns on the nightly rebuild with the window you chose. ### Can I include orders that aren’t `completed`? Yes. On the **Settings** tab, **Order statuses** lists every status, including custom ones added by other plugins (for example “Shipped”). Shortcuts pick Completed only, every paid status, or everything. The scheduled writer, the late-status hook, the admin backfill and the nightly rebuild all use your selection. The page warns you when you select a status where the customer hasn’t paid (pending payment, on hold, failed, cancelled, refunded): those customers didn’t buy, and failed orders often come from bots testing stolen cards. When an order leaves your selection (for example Completed Refunded), the customer is removed at the next nightly rebuild, unless another of their orders still qualifies. For a one-off run with other statuses, use `wp cmls backfill --statuses=processing, completed,on-hold` or `--all-statuses`. ### What are value segments? Extra files that hold only some of your customers, each with its own URL to add in Google Ads as a separate Customer Match list. Turn them on under **Value segments**, then add up to 5 segments from a template or your own rules: * **Minimum spend:** a fixed amount in your store currency, or the top X% of customers by spend (follows your store as it grows). * **Minimum orders:** 2 or more for repeat buyers. * **Last order:** within the last N days, or not in the last N days (big spenders who stopped buying, for win-back campaigns). Spend is a customer’s total across their paid orders, either the order total or net sales (without tax and shipping), with refunds subtracted. It’s counted over the audience window or over all orders ever, but a customer always needs an order inside the window to be in any file. If your orders use more than one currency, you can leave the other currencies out of the totals or convert them at rates you enter. Segments are recalculated at every nightly rebuild. Google doesn’t serve lists with fewer than about 100 members, so the admin flags small segments. By default each segment is one file for all countries; you can split them by country. ### How is the deduplication table sized? One row per unique `(email_hash, country)`. At ~110 bytes per row, 1M unique customers across all countries is roughly 100 MB. While a rebuild runs, a second copy is filled next to it (plus a per-customer totals table when value segments are on), so plan for about twice that during the rebuild. The spare copies are emptied when it finishes. ### Will deactivating WooCommerce break it? The plugin’s admin page shows a notice and stops scheduling cron, but data isn’t lost. Re-activate WC and the plugin resumes from the noted order. If you uninstall the plugin then the `uninstall.php` routine cleans up the option keys, database tables, and any generated files. ### GDPR / privacy The files contain hashed personal information (email, phone, name) and plaintext country + ZIP. Treat the directory and its access URLs as sensitive data! The plugin only creates files on your own server and does not read consent-management records: every order in the selected range is exported as-is. Whether a given customer may be included in an advertising audience — and whether Google or Meta may receive the file — depends on your store’s consent setup and local legal requirements; applying them is your responsibility as the data controller. If a customer requests deletion under GDPR / similar: 1. Delete or anonymize the WooCommerce order(s). 2. Wait for the nightly rebuild, or click **Tools Rebuild now** (`wp cmls rebuild`)— the deleted customer is gone from every file, value segments included. Targeted per-row deletion isn’t supported on purpose: the SHA-256 hashing is one- way and rebuilding from source is fast. ## Reviews There are no reviews for this plugin. ## Contributors & Developers “CMLS – Customer Match List for Google Ads & Meta Ads” is open source software. The following people have contributed to this plugin. Contributors * [ Eduard Doloc ](https://profiles.wordpress.org/rwky/) [Translate “CMLS – Customer Match List for Google Ads & Meta Ads” into your language.](https://translate.wordpress.org/projects/wp-plugins/customer-match-list-google-ads) ### Interested in development? [Browse the code](https://plugins.trac.wordpress.org/browser/customer-match-list-google-ads/), check out the [SVN repository](https://plugins.svn.wordpress.org/customer-match-list-google-ads/), or subscribe to the [development log](https://plugins.trac.wordpress.org/log/customer-match-list-google-ads/) by [RSS](https://plugins.trac.wordpress.org/log/customer-match-list-google-ads/?limit=100&mode=stop_on_copy&format=rss). ## Changelog #### 2.0.0 * New: audience window (all orders, last 365 or 540 days, or custom). Every night the files are rebuilt from the orders inside the window and swapped in at once, so customers who stopped buying drop out. Feed URLs stay the same. Also available as “Rebuild now” in the admin and `wp cmls rebuild`. * New installs start with a 540-day window. Sites updating from 1.x keep their append-only files, with no nightly rebuild, until the Settings tab is saved once. * New: choose which order statuses count, including custom statuses from other plugins. The scheduled writer, the late-status hook, the admin backfill and the rebuild all use the selection. * New: value segments — up to 5 extra lists by spend (top X% or a minimum amount), order count and last order date, with templates, net or total spend, refunds subtracted and multi-currency handling. * New: the admin page is split into Feeds, Settings, Value segments and Tools tabs, with “Run now” and “Rebuild now” buttons. * Fix: the scheduled writer and the late-status hook no longer add orders older than the window (backdated or imported orders). * Fix: when a CSV write fails, those customers are no longer marked as exported; the next run writes them. * Fix: a new country file can no longer lose rows written at the same moment by another process. * Fix: saving the settings without changing the interval no longer reports “Invalid interval”. * WP-CLI: new `wp cmls rebuild`; `wp cmls backfill` now defaults to the statuses saved in the settings; `wp cmls status` also shows the audience window, statuses and rebuild times. * The suggested privacy-policy text now covers the selected statuses, value segments and the nightly rebuild. * Admin JavaScript no longer uses inline event handlers. * Tested with WordPress 7.1 and WooCommerce 11.2. #### 1.1.2 * Orders that turn “completed” late (delayed payments, manual completion) are now appended the moment they complete instead of being missed by the scheduled writer. * “Delete all files & reset dedup” no longer causes the next scheduled run to rebuild the entire order history — rebuilding stays explicit via backfill. * New FAQ on Google’s automatic conversion-based customer lists. #### 1.1.1 * Consistent plugin name: “Customer Match List for Google Ads”. The exported files also work for Meta Ads Custom Audiences (see FAQ) — same hashing. * Confirmed compatibility with WooCommerce 10.9. * Readme and documentation cleanup. No functional changes. #### 1.1.0 * Feed URLs now end in `.csv` so Google Ads’ HTTPS connector accepts them. * Hashing normalization aligned with the Google Customer Match spec (Unicode-aware lowercase, name punctuation stripping, US ZIP truncation, double-hash guard). * Fresh activations no longer sweep historical orders — backfill is explicit (admin button or WP-CLI). * Admin JS moved into enqueued, page-scoped files. * Added suggested privacy-policy text, sub-100-row serving warning, CSV-injection hardening on zip values, and removed the REST authentication override. #### 1.0.0 * Initial release: per-country CSVs with `(identity, country)` dedup, WP-CLI and Action Scheduler backfills, tokenized REST download endpoint, HPOS-first SQL. ## Meta * Version **2.0.0** * Last updated **1 روز ago** * Active installations **40+** * WordPress version ** 6.0 or higher ** * Tested up to **7.1.3** * PHP version ** 7.4 or higher ** * Language * [English (US)](https://wordpress.org/plugins/customer-match-list-google-ads/) * Tags * [google ads](https://haz.wordpress.org/plugins/tags/google-ads/)[meta ads](https://haz.wordpress.org/plugins/tags/meta-ads/) [woocommerce](https://haz.wordpress.org/plugins/tags/woocommerce/) * [Advanced View](https://haz.wordpress.org/plugins/customer-match-list-google-ads/advanced/) ## Ratings No reviews have been submitted yet. [Your review](https://wordpress.org/support/plugin/customer-match-list-google-ads/reviews/#new-post) [See all reviews](https://wordpress.org/support/plugin/customer-match-list-google-ads/reviews/) ## Contributors * [ Eduard Doloc ](https://profiles.wordpress.org/rwky/) ## Support Got something to say? Need help? [View support forum](https://wordpress.org/support/plugin/customer-match-list-google-ads/) ## Donate Would you like to support the advancement of this plugin? [ Donate to this plugin ](https://www.paypal.me/eduardvd)