Skip to main content

Events Not Firing

A specific ecommerce or engagement event is not appearing in the GTM data layer.

Always use GTM Preview mode

The most reliable way to debug missing events is to use GTM Preview mode (gtm.google.com → Preview). The browser network tab and GA4 DebugView alone are not enough — they may miss events that fire late in the page lifecycle via dataLayer.push().

How Events Are Delivered​

Most WHMCS GTM events use a session queue mechanism:

  1. The event is generated server-side during a WHMCS hook (e.g. ClientAreaFooterOutput, AfterShoppingCartCheckout).
  2. It is stored in $_SESSION['dataLayerPush'].
  3. On the next page load, the session queue is flushed and the events are output as dataLayer.push({...}) calls in the page footer.

This means events typically appear one page after the action that generated them, not on the same page. This is by design and ensures the GTM container is already initialized before any pushes occur.

begin_checkout Not Appearing​

Cause A — Checkout page action not reached​

The begin_checkout event is generated when the user visits cart.php?a=checkout — the page with billing details and the payment method selector. If your order form template or payment gateway redirects the user away before this page renders, the event will never be queued.

Check: Manually navigate to https://yourwhmcs.com/cart.php?a=checkout with items in the cart. Then proceed to the confirmation page. Check GTM Preview on the confirmation page for a begin_checkout push.

Common scenarios where this step is skipped:

  • Payment gateways that redirect immediately after "Order Now" (bypassing the checkout step).
  • Custom order form templates that merge the configure and checkout steps into one page.
  • WHMCS installs with AutoRedirectoInvoice enabled (redirects straight to the invoice, skipping the confirmation page where the queued push would fire).

Cause B — Session not persisting between requests​

If your WHMCS installation uses a different session handler, or if the user's browser blocks session cookies, the $_SESSION['dataLayerPush'] queue will be lost between the checkout page and the confirmation page.

Check: Verify that PHP sessions are working correctly on your server. You can do this by checking if the WHMCS login session persists normally.

Cause C — GTM trigger not configured​

Verify that the WHMCS EE — Begin Checkout trigger in your GTM container is set as a Custom Event with the event name exactly begin_checkout (lowercase, with underscore). Refer to the Container Template if you need reference.

purchase Event Not Appearing​

The purchase event is fired via the AfterShoppingCartCheckout WHMCS hook, which runs during the checkout POST request (when the customer submits the checkout form). It is stored in the session and pushed on the next page — typically the order confirmation page.

Cause A — Order placed by admin​

If an admin creates an order on behalf of a client from the WHMCS admin panel (ordersadd.php), the module detects this and does not push a client-side data layer event. Instead, it attempts to send the event via the Measurement Protocol (server-to-server) if a GA4 API Secret is configured.

If you are testing with admin-placed orders and wondering why GTM Preview shows no purchase event, this is by design.

Cause B — GA4 Measurement ID not set (skips server-side send)​

The purchase hook will return false and do nothing at all if the GA4 Measurement ID (ga_trackingid) is empty in the module settings.

Check: Go to Addons → Google Tag Manager → Google Analytics and verify the Measurement ID field is filled in.

caution

This means: if you have never filled in the Measurement ID, no purchase event will ever fire — not even the client-side data layer push. This is a known current behavior.

Cause C — Confirmation page not loaded​

If the payment gateway redirects the customer to an external page (PayPal, Stripe hosted checkout, etc.) and does not return them to the WHMCS confirmation page, the session queue is never flushed and the purchase event is never delivered to the browser.

Fix for off-site gateways: Use the Measurement Protocol (server-side event) by configuring both the GA4 Measurement ID and API Secret in the module settings. Server-side events fire independently of the browser page load.

view_cart Not Appearing​

The view_cart event fires when templatefile === 'viewcart' and action === 'view'. This corresponds to the standard cart page (cart.php?a=view).

Common causes of it not appearing:

  • Your order form template does not use the standard viewcart template file name.
  • The cart is empty — the event still fires, but check if your GTM trigger requires ecommerce.items to be non-empty.

sign_up / login Not Appearing​

These events use separate WHMCS hooks (ClientAdd, UserLogin) and are queued the same session way. They will appear on the first page load after the registration or login action.

If they consistently do not appear even after login:

  • Confirm the user was not already logged in (the login event only fires on active login actions, not on page refreshes with an existing session).
  • Check the redirect URL after login — if it redirects to an external page, the session push will be lost.

Events Only Appear After a Page Refresh​

This is expected behavior for all events that use dataLayerPushRemember. The event is queued server-side during one request and delivered client-side on the next. If you are looking for an event on the same page where the action happens (e.g. add_to_cart on the cart page), check the following page after adding to cart.