Skip to main content

Facebook Conversions API (CAPI) — Improving Event Match Quality

This guide explains how to use the customer data available in the WHMCS GTM data layer to improve your Facebook CAPI Event Match Quality score, which directly impacts the accuracy of conversions tracked via the Meta Conversions API.

Feature Requirements
  • Module version v4.2+
  • Enhanced Conversions option enabled (see below)
  • User must be logged in for customer PII to be present in the data layer

Why Event Match Quality Is Low by Default​

Facebook measures Event Match Quality (EMQ) on a scale from 0–10. A low score (e.g., 4/10) means Facebook cannot reliably match your events to a Facebook user, which reduces the effectiveness of your ad campaigns.

The most common cause of low EMQ is missing customer identifiers in the event payload — specifically email, phone, name, address, and Facebook cookies (_fbp, _fbc).

By default, the WHMCS GTM module only pushes basic user properties (loggedin, userType, locale) and ecommerce data to the data layer. The full customer PII block (customerData) requires a dedicated setting to be enabled.

Step 1 — Enable Enhanced Conversions in the Module​

  1. In your WHMCS Admin, go to Addons → Google Tag Manager.
  2. Click the "Enhanced User Conversion" menu tab.
  3. Under "Enhanced Conversions for Web", check "Enable Enhanced Conversions".
  4. Click Save.

Enable Enhanced Conversions setting

Once saved, the module will inject a customerData object into the GTM data layer on every page load for logged-in users.

Step 2 — Verify the Data Layer​

After enabling the setting, log in to your WHMCS store as a client and open GTM Preview mode. In the Data Layer tab you should see a customerData object similar to:

{
  "customerData": {
    "customer_uuid": "c0a8a7b1-1b1b-4b1b-8b1b-1b1b1b1b1b1b",
    "customer_status": "Active",
    "email": "[email protected]",
    "email_hash": "b94d27b9934d3e...",      // SHA-256 of lowercase email
    "first_name": "John",
    "first_name_hash": "96d9632f363564...", // SHA-256
    "last_name": "Doe",
    "last_name_hash": "799ef92a11af918...", // SHA-256
    "phone": "+1234567890",
    "phone_hash": "a41d5b5c8d3e74...",      // SHA-256
    "company_name": "Acme Ltd.",
    "address": {
      "street": "123 Main St",
      "city": "New York",
      "region": "NY",
      "country": "US",
      "postal_code": "10001"
    }
  }
}
note

All sensitive fields are available both in plain text and SHA-256 pre-hashed form. Facebook CAPI accepts either format — prefer the hashed values (email_hash, phone_hash, etc.) when building server-side events, and plain values for client-side Enhanced Conversions (Google will hash them automatically).

Step 3 — GTM Variables (Already Included in the Container Template)​

If you imported the WHMCS GTM Container Template, all customer data variables are already created inside the "WHMCS Customer Data" folder. No manual configuration is needed for this step.

The following variables are pre-built in the template and map directly to the customerData object pushed by the module:

GTM Variable Name (in template)Data Layer VariableNotes
Customer Data - EmailcustomerData.emailLowercase plain email
Customer Data - Email (hash)customerData.email_hashSHA-256 pre-hashed
Customer Data - PhonecustomerData.phoneInclude country code
Customer Data - Phone (hash)customerData.phone_hashSHA-256 pre-hashed
Customer Data - First NamecustomerData.first_name
Customer Data - First Name (hash)customerData.first_name_hashSHA-256 pre-hashed
Customer Data - Last NamecustomerData.last_name
Customer Data - Last Name (hash)customerData.last_name_hashSHA-256 pre-hashed
Customer Data - CitycustomerData.address.city
Customer Data - RegioncustomerData.address.regionState / province code
Customer Data - CountrycustomerData.address.countryISO 2-letter code
Customer Data - Postal CodecustomerData.address.postal_code
Customer Data - StreetcustomerData.address.street
Not using the Container Template yet?

If you configured your GTM container manually (without importing the template), you will need to create these variables yourself as Data Layer Variables. See the Container Template documentation to learn how to import it and avoid manual setup.

Step 4 — Capture Facebook Cookies (_fbp and _fbc)​

The _fbp and _fbc cookies are set by the Meta Pixel script in the visitor's browser. They are not injected into the GTM data layer by the WHMCS GTM module — they are already available as browser cookies once the Pixel fires.

To read them in GTM, create two variables of type 1st Party Cookie:

GTM Variable NameVariable TypeCookie Name
cookie - _fbp1st Party Cookie_fbp
cookie - _fbc1st Party Cookie_fbc
tip

_fbp is always set when the Meta Pixel loads. _fbc is only set when the visitor arrived via a Facebook ad (contains the fbclid click ID). Both fields significantly improve EMQ when present.

Step 5 — Map Variables in Your Facebook CAPI Tag​

In your Facebook Conversions API tag (whether using a custom GTM tag, a Meta Pixel tag, or a server-side tag), map the GTM variables to the corresponding User Data fields. Use the variable names from the Container Template:

Facebook CAPI FieldGTM Variable
em (email){{Customer Data - Email}}
ph (phone){{Customer Data - Phone}}
fn (first name){{Customer Data - First Name}}
ln (last name){{Customer Data - Last Name}}
ct (city){{Customer Data - City}}
st (state){{Customer Data - Region}}
zp (postal code){{Customer Data - Postal Code}}
country{{Customer Data - Country}}
fbp{{cookie - _fbp}}
fbc{{cookie - _fbc}}
Pre-hashed values

If your Facebook CAPI implementation requires pre-hashed SHA-256 values (e.g. in a server-side setup), use the (hash) variants instead: {{Customer Data - Email (hash)}}, {{Customer Data - Phone (hash)}}, {{Customer Data - First Name (hash)}}, {{Customer Data - Last Name (hash)}}. Do not send both plain and hashed values for the same field in the same event.

Expected Results​

With all the above fields populated, your Event Match Quality score should increase from a typical 4/10 to 7–9/10. The actual score depends on:

  • How completely your customers have filled in their WHMCS profile (phone, address, etc.)
  • Whether the visitor arrived via a Facebook ad (presence of _fbc)
  • The consistency of the email used to sign up on WHMCS vs. their Facebook account
info

EMQ scores above 7/10 are considered high quality by Meta and will meaningfully improve your remarketing audience accuracy and conversion attribution.

Important Limitations​

  • customerData is only pushed for logged-in clients. Events fired for guest or unauthenticated sessions will not include customer PII.
  • If a client has not filled in their phone number or address in WHMCS, those fields will be empty strings and will not contribute to EMQ.
  • This feature requires the client to be logged in before the conversion event fires. For new client registrations, the data will be available from the registration confirmation page onward.