How Purchases Are Reported
A purchase is reported when the money is received, not when the cart is closed. This page explains what the module sends, when it sends, and what happens when the same invoice is paid twice or viewed again later.
When a sale counts
The module listens to InvoicePaid. That hook fires whenever WHMCS records a payment against an invoice, which includes:
- a gateway callback or a payment captured by the recurring billing cron
- an invoice marked as paid by an administrator
- an invoice paid with the customer's account credit
- a payment applied days after the order was placed
The reported value is the money actually received, read from the payment rows of the invoice (SUM(amountin - amountout)). Nothing is reported when an order is created, when the checkout page is submitted, or while the invoice is still unpaid. An order that is never paid produces no revenue in Analytics.
Line items come from the invoice itself, so the value of the event is the sum of what was charged, never the catalogue price of the products.
Two delivery paths
Server-side, through the Measurement Protocol. This is the primary path. It requires a GA4 Measurement ID and an API secret in the module configuration, and it runs inside the InvoicePaid hook. It does not depend on the customer being online: if the payment is confirmed by a webhook at 3 AM, the hit is sent at 3 AM.
Browser-side, through the data layer. This is a fallback. It exists for installations that do not configure the Measurement Protocol, where the server has no way to reach Analytics and revenue would otherwise be invisible. It fires when a customer opens a recently paid invoice, limited to payments made in the last two hours so that opening an old invoice never reports its revenue again.
The fallback stays silent whenever the server-side path already delivered the sale, so a customer who pays and then returns to the invoice does not generate a second event.
One sale, one hit
The module keeps a ledger table, mod_whmcsgtm_revenue_log, with one row per invoice and event type. The pair (invoiceid, kind) is unique, and the row is claimed before the hit is sent. This is what makes the reporting idempotent:
- a gateway that calls the same callback twice
- a hook that runs again after a page refresh
- a payment split into several transactions on the same invoice
All of those produce a single purchase. A claim is only released when the send fails at the transport level (timeout, connection error, HTTP 5xx), because in that case nothing arrived and a retry is legitimate.
A delivered purchase whose received amount is lower than the invoice total is recorded as partial. It counts as delivered, so a later page view does not report it again.
What the event carries
transaction_id: the order id, which is the identifier the module has always used. When an invoice has no order, the invoice number is used, and then the invoice id.valueandtax: the amount received and the tax recorded on the invoice, as numbers.currency: taken from the customer's currency, since WHMCS does not store a currency on the invoice itself.items: one entry per invoice line, with the product id resolved from the service, the description, and the line amount.revenue_type:new,renewal,upgradeoraddon, classified from the invoice lines. A service registered on the invoice date counts as a new sale.coupon: the order's promo code, present only when the order used one.client_id: the analytics client id captured from the_gacookie at checkout and stored with the customer. When the payment arrives after the cookie is gone, the hit carries a timestamp-basedsession_idinstead of the original session.
Attribution limits
When the hit is sent from the server with a client_id and session_id taken from the cookie, Analytics attributes the sale to the original session and campaign. When the payment arrives long after the visit, the cookie is usually gone, and the sale is still counted but lands as direct traffic instead of the campaign that brought the customer. Revenue correctness comes first; campaign attribution for late payments is what the reconciliation work in later releases addresses.
Refunds
Cancelling and refunding an order sends a refund event carrying the same transaction_id, the same client identity and the refunded items, so Analytics can subtract it from the reported revenue.
The refund goes through the ledger like a purchase: it is claimed before sending and delivered once. It is only sent when the original purchase was actually reported, so cancelling an order that was never paid does not create a refund with no matching sale. The refunded amount is read from the payment rows (amountout), not from the order total.
When a purchase is missing
Check the ledger first:
SELECT invoiceid, kind, amount, currency, status, reason, created_at
FROM mod_whmcsgtm_revenue_log
WHERE invoiceid = 1234;
sent: the hit left the server. If Analytics still shows nothing, check the Measurement ID and API secret, and remember that a payload without currency is silently discarded by Google.error: the row was claimed but never marked, which means the request did not complete. The claim is released on transport failures, so a later run can retry.skipped: the invoice had no money received, for example a zero value payment.
No row at all means InvoicePaid never ran for that invoice, which points to the invoice not being paid inside WHMCS.