XeroWP
CMLS – Customer Match List for Google Ads & Meta Ads
CMLS – Customer Match List for Google Ads & Meta Ads

CMLS – Customer Match List for Google Ads & Meta Ads

0/5 (0 ratings) 30 active installs Updated Jul 17, 2026
cmlscustomer matchgoogle adsmeta adswoocommerce
Download v1.1.2
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.

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. A one-time backfill walks every completed WooCommerce order, splits them by billing country, hashes the customer fields and writes one CSV per country.
  2. A scheduled job (1, 6, 12, or 24 hours) picks up new completed orders since the last run and appends them to the right country file. Orders that turn completed late (delayed payment confirmation, manual completion) are appended the moment they complete, so they are never missed.
  3. 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.

Features

  • Per-country splitting — one CSV per ISO billing country, never mixed.
  • Background backfill 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.
  • 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:

  • Pick the cron interval (1/6/12/24 h).
  • See the access token; reset it (regenerates every URL, renames every file).
  • See per-country status: row count, file size, and the tokenized URL ready to copy.
  • Start a background backfill with a date-range preset.
  • Watch backfill progress live (orders processed, rows written, rows skipped, watermark).
  • Delete every country file and reset the dedup table.
  • Do an automated check that confirms the webserver does not expose the CSV directory via a public file listing.

WP-CLI

  • wp cmls backfill — one-time backfill of historical orders, split by country. Flags: --statuses=completed (default), --all-statuses, --days=N, --since=YYYY-MM-DD, --until=YYYY-MM-DD, --dry-run, --batch-size=5000, --force.
  • 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.
  • 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.