Server-Side Tracking for OpenCart: GA4, Meta Conversions API, TikTok

Overview

Send your shop's e-commerce events from your own server to the free, official endpoints of Google Analytics 4, Meta and TikTok. Ad blockers, browser privacy limits and closed tabs no longer cost you purchases, and every event is deduplicated with the browser pixel.

• GA4 Measurement Protocol: purchase, refund, add_to_cart, begin_checkout, sign_up / generate_lead and (optional) view_item, with the visitor's GA client id and session id
• Meta Conversions API: Purchase, AddToCart, InitiateCheckout, ViewContent, Lead and CompleteRegistration, with SHA-256 hashed customer data, IP, user agent, fbp and fbc
• TikTok Events API (free with a TikTok Ads account): CompletePayment, AddToCart, InitiateCheckout, ViewContent, Contact and CompleteRegistration
• Deduplication: the server event and the browser tag share one event id; purchases use purchase.<order id>
• Optional browser tags: gtag.js with Consent Mode v2, the Meta Pixel and the TikTok Pixel, firing the same events with the same ids
• Consent-aware: built-in banner, the OpenCart 4.1 cookie bar, Cookiebot, CookieYes, the Kavio Labs consent banner or any cookie rule; GA4 needs analytics consent, Meta and TikTok need marketing consent
• Order status mapping: you choose which statuses are a purchase and which are a refund; works for checkout, payment callbacks and status changes in the admin
• Queue with retries: events are queued, sent after the page is delivered, and retried after 1 min, 5 min, 15 min, 1 h and 3 h; OpenCart's cron or a cron URL picks up the rest
• Test mode: Meta and TikTok test event codes, GA4 validation endpoint; connection test buttons for every destination
• Event log: every request body and answer, status, retries, filters, purge policy; dashboard counters
• Official endpoints only: no paid service, no relay server, no Google Tag Manager server container
• No core file changes and no OCMOD: OpenCart events only
• OpenCart 4.0.2.0 – 4.1.x and 3.0.3.x – 3.0.5.x, one license for both

Installation

Requirements

• OpenCart 4.0.2.0 – 4.1.x (package kv_server_side_tracking.ocmod.zip) or 3.0.3.x – 3.0.5.x (package kv_server_side_tracking-oc3.ocmod.zip)
• PHP 7.4 or newer with cURL (OpenCart 4.1 and 3.0.5 need PHP 8.1+)
• Your server must be allowed to open HTTPS connections to www.google-analytics.com (or region1.google-analytics.com), graph.facebook.com and business-api.tiktok.com
• A GA4 property, a Meta dataset (pixel) and / or a TikTok Ads pixel. All three endpoints are free.

OpenCart 4

1. Extensions > Installer: upload kv_server_side_tracking.ocmod.zip and click Install.
2. Extensions > Extensions, type Modules: find Server-Side Tracking, click Install (green +), then Edit.
3. Fill in at least one destination (tabs Google Analytics 4, Meta, TikTok), press the connection test button, then Save.
4. System > Maintenance > Cron Jobs lists "Server-Side Tracking: send queued events and retries" (hourly). It runs when your server calls the OpenCart cron (index.php?route=cron/cron). Without it, retries still run on store and admin traffic.

OpenCart 3

1. Extensions > Installer: upload kv_server_side_tracking-oc3.ocmod.zip.
2. Extensions > Modifications: click Refresh (the package changes no files, but OpenCart lists it there).
3. Extensions > Extensions, type Modules: install Server-Side Tracking, then Edit.
4. Fill in a destination, test, save.
5. Recommended: add the Cron URL from the Delivery & log tab to your hosting's cron jobs, every 5–15 minutes, for example wget -q -O /dev/null "<cron URL>". OpenCart 3 has no cron table of its own.

Updating

Upload the new package the same way. On OpenCart 4, uninstall and delete the old entry under Extensions > Installer first; keep the module itself installed under Extensions > Modules so your settings and the event log stay.

Uninstalling

Extensions > Extensions > Modules > Server-Side Tracking > Uninstall removes the events, the cron job, the settings and the two tables (kv_sst_event, kv_sst_order).

Configuration

Extensions > Extensions > Modules > Server-Side Tracking. The Dashboard tab shows what was delivered in the last 7 days and a setup checklist.

Google Analytics 4

• Measurement ID (G-…) and API secret: Google Analytics > Admin > Data streams > your web stream > Measurement Protocol API secrets > Create.
• Endpoint: global or EU (region1.google-analytics.com).
• Send from the server: tick the events GA4 should receive from the server. An event sent from the server is not fired by the browser tag (GA4 does not merge the two, except purchases by transaction id).
• Send user_id: logged-in customers are sent with their OpenCart customer id.
• Print gtag.js: only if no other extension or your theme loads Google Analytics. It runs with Consent Mode v2.
• Validate GA4 setup sends a sample purchase to the Google validation endpoint (nothing is recorded). Google does not check the API secret there; after saving, switch test mode on, place a test order and look at DebugView.

Meta

• Dataset / Pixel ID and Access token: Events Manager > your dataset > Settings > Conversions API > Generate access token.
• Test event code: Events Manager > Test events. Used only while test mode is on.
• Graph API version: change only when Meta retires the version shown.
• Print the Meta Pixel: loads the pixel after marketing consent and fires the same events with the same event ids. If another extension already prints the pixel, leave this off; deduplication then needs that pixel to send the same event ids.
• Test Meta connection reads the dataset with your token; with a test event code it also sends one event to Test events.

TikTok

• Pixel code and Access token: TikTok Ads Manager > Tools > Events > Web events > your pixel > Settings > Generate access token.
• Test event code: needed for the connection test, used only while test mode is on.
• Print the TikTok Pixel: works like the Meta Pixel option.

Orders & events

• Purchase statuses: a purchase is sent once, when the order first reaches one of them (none ticked = the store's processing and complete statuses). Leave "Pending" off if you only want paid orders (bank transfer, cash on delivery).
• Refund statuses: a GA4 refund is sent once when a reported order reaches one of them. Default: Refunded, Reversed, Chargeback.
• Value: order total (with tax and shipping) or products without tax and shipping.
• Item id: product ID, model or SKU. Use what your Merchant Center / Meta / TikTok catalogue uses.
• Leads: account registration (sign_up / CompleteRegistration) and the contact form (generate_lead / Lead / Contact).
• Skip bots and Ignore IP addresses (your office, staff; a value ending in "." matches a whole IPv4 range).

Consent

Before a decision: do not send (opt-in, EU / UK) or send (opt-out regions). GA4 needs analytics consent, Meta and TikTok marketing consent. Purchases use the consent given at checkout.

Delivery & log

• Test mode: GA4 events go to the validation endpoint (checked, not recorded; findings in the event log), Meta / TikTok events carry your test event codes.
• Send events: at the end of the request (recommended; on PHP-FPM / LiteSpeed the page is delivered first) or only by the queue worker (cron).
• Cron URL: secret link that runs the queue; call it from your server's cron.
• Keep events: delivered, failed and expired events older than this are deleted (default 30 days).
• Keep request bodies: off removes the body of a delivered event right after delivery.

Usage

What is sent, and when

The browser context of the order (GA client and session id, fbp, fbc, TikTok ids, IP, user agent, consent) is stored at checkout, so a purchase is matched to the visitor even when a payment callback or your admin changes the status later.

Event log

Marketing > Tracking events (also the list button on the settings page):

• status tabs: delivered, waiting, failed, expired; filters by destination, event, order and date
• click a row to see the request body and the full answer of Google, Meta or TikTok
• Retry selected, Retry all failed, Send queue now, Delete old events
• the menu entry shows the number of failed events of the last 24 hours

Built-in consent banner

Shown at the bottom of every page until the visitor decides: "Accept all", "Analytics only" or "Necessary only". The texts are in the storefront language file of the extension (shared file lang/en-gb.php in the extension library folder).

Going live checklist

1. Connection test green for every destination you use.
2. Test mode on, place a test order, set it to a purchase status in the admin, check GA4 DebugView, Meta Test events and TikTok Test events.
3. Test mode off.
4. Cron set up (OpenCart 4: the OpenCart cron; OpenCart 3: the cron URL).
5. Mention server-side tracking in your privacy policy.

FAQ

Do I need Google Tag Manager server-side, Stape or another paid service?

No. The extension talks directly to the official, free endpoints: GA4 Measurement Protocol, Meta Conversions API and TikTok Events API. There is no relay server in between.

Will purchases be counted twice?

No. Server and browser events share one event id (purchase.<order id> for purchases), and Meta and TikTok keep one of them. GA4 events sent from the server are not fired by our browser tag; GA4 also deduplicates purchases by transaction id.

I already have a pixel or gtag from another extension. Leave our browser tag options off. Server events still work. For Meta / TikTok deduplication the other pixel must send the same event ids; if it cannot, send those events from the server only or switch our pixel on instead.

What customer data is sent?

Meta and TikTok receive e-mail, phone, name, city, postcode, region and country as SHA-256 hashes, plus IP address, user agent and their own browser / click ids. GA4 receives no personal data (client id, session id and optionally the customer id as user_id). Access tokens and API secrets are never written to the event log.

How does consent work?

Choose the consent source on the Consent tab. Without analytics consent nothing goes to GA4; without marketing consent nothing goes to Meta and TikTok, and their pixels are not loaded. The decision at checkout is stored with the order.

My payment provider confirms orders later. Is the purchase still matched to the visitor?

Yes. The visitor's ids, IP, user agent and consent are stored when the order is created and used when the order reaches a purchase status, from a callback, the admin or the API.

What happens when Google, Meta or TikTok is down?

The event stays in the queue and is retried after 1 min, 5 min, 15 min, 1 h and 3 h. GA4 accepts events up to 72 hours old, Meta and TikTok up to 7 days; older queued events are marked expired.

Does the extension slow down my store?

Events are written to a queue table during the request. With "at the end of the request" delivery they are sent after the page has been delivered (PHP-FPM, LiteSpeed), with short time-outs. You can also leave sending to the cron completely.

Does it change OpenCart core files?

No. It uses OpenCart events only, no OCMOD.

OpenCart 3: do I need a cron job?

Recommended. OpenCart 3 has no cron table; the extension delivers events at the end of each request and retries on normal traffic, but a cron call of the Cron URL every 5–15 minutes makes retries steady.