AxiTrace for Magento 2 / Adobe Commerce
A start-to-finish walkthrough: install the Composer module, paste your workspace public key, optionally configure a first-party tracking subdomain, and verify the first server-side purchase event lands in your AxiTrace dashboard. About ten minutes from blank to fully wired.
Before you start
You will need:
- An AxiTrace account with at least one workspace. Create one for free (10,000 visits/month, no card required).
- A Magento 2 store running Magento Open Source or Adobe Commerce 2.4.6, 2.4.7, or 2.4.8 on-prem, PHP 8.1 - 8.4.
- SSH / CLI access to run
bin/magentocommands (and Composer if installing via Composer). - About 10 minutes. Less if you skip the custom domain step.
Adobe Commerce as Cloud Service (ACCS) does not support traditional PHP modules - it uses App Builder extensions. ACCS stores are not supported by this module.
Compatibility
| Requirement | Supported versions |
|---|---|
| Magento Open Source | 2.4.6 · 2.4.7 · 2.4.8 |
| Adobe Commerce on-prem | 2.4.6 · 2.4.7 · 2.4.8 |
| PHP | 8.1 · 8.2 · 8.3 · 8.4 |
| Luma theme | Supported out of the box |
| Hyva theme | Via separate axitrace/module-tracking-hyva package |
| Adobe Commerce as Cloud Service (ACCS) | Not supported |
Copy your workspace public key
The public key (always starts with pk_live_) identifies your AxiTrace workspace. The Magento module uses it to authenticate every event it sends.
- Sign in at axitrace.com/login with your email and password.
- You land on the Workspaces page. Click the workspace name you want to connect to your store.
- The workspace opens on Overview. Click Workspace settings in the sidebar, open Tracking & domains and find the Container Information card.
- Click the small copy icon next to the Public Key field - you should see a “Copied to clipboard!” toast.
Paste the pk_live_-prefixed public key into Workspace public key. The Secret Key belongs only in the AxiTrace secret key (optional) field, which turns on profit tracking: Magento stores it encrypted, it never reaches the storefront and it is sent only over https to AxiTrace. Never put it in any other field, in the theme or in a tag manager.
Install via Composer (recommended)
Run the following command from your Magento root directory. It installs the core tracking module and the Hyva compatibility package, enables both, and runs the upgrade scripts:
composer require axitrace/module-tracking axitrace/module-tracking-hyva && bin/magento module:enable AxiTrace_Tracking Hyva_AxiTraceTracking && bin/magento setup:upgrade && bin/magento cache:clean
If your store uses the Luma theme and you do not plan to switch to Hyva, omit the Hyva package and module from the command:
composer require axitrace/module-tracking && bin/magento module:enable AxiTrace_Tracking && bin/magento setup:upgrade && bin/magento cache:clean
Install via ZIP (alternative)
For hosting environments without Composer access, download the ZIP and follow these steps:
- Download the ZIP from axitrace.com/downloads/axitrace-magento-plugin-latest.zip (or use the button at the top of this page).
- Extract the archive into
app/code/AxiTrace/Trackingon your Magento server. The directory structure must end up asapp/code/AxiTrace/Tracking/registration.php. - From the Magento root, run:
bin/magento module:enable AxiTrace_Tracking && bin/magento setup:upgrade && bin/magento cache:clean
After uploading, make sure the app/code/AxiTrace/Tracking directory is owned by the web-server user (typically www-data) or whichever user runs the Magento CLI. Incorrect permissions prevent setup:upgrade from registering the module.
Configure the module
Once the module is enabled, configure it from Magento Admin:
- Open Stores → Configuration → AxiTrace → General.
- Set Enable AxiTrace Tracking to Yes.
- Paste the workspace public key you copied in Step 1 into the Workspace Public Key field. The value is encrypted at rest in Magento’s
core_config_datatable. - (Optional) Click Auto-Detect Domain - if you have a verified custom tracking domain (e.g.
axi.yourshop.com) in your AxiTrace workspace, it is detected and auto-populated here. You can also type it manually; use the hostname only, no scheme or path. - Click Test Connection. The status indicator turns green within approximately 3 seconds if the key is valid and the AxiTrace ingestion API is reachable.
- Click Save Config.
Configuration field reference
| Field | Required | Notes |
|---|---|---|
| Enable AxiTrace Tracking | Required | Yes / No toggle. Must be set to Yes for any events to fire. |
| Workspace Public Key | Required | Starts with pk_live_ (production) or pk_test_ (test workspace). Stored encrypted in core_config_data. |
| Auto-Detect Domain | Optional | Button that contacts AxiTrace API with your public key and auto-fills a verified custom tracking domain. |
| Custom Tracking Domain | Optional | Hostname only, e.g. axi.yourshop.com. Leave blank to use the default stat.axitrace.com. |
Place a test order
The fastest way to confirm everything is wired up is a real (or staging) order. We recommend a free-shipping method or cash on delivery so you do not trigger your live payment processor.
- Open your store in a fresh incognito window (so you are an anonymous visitor, not a logged-in admin).
- Browse a few products, click Add to Cart, proceed to checkout, and complete an order.
- Once the order transitions to the
processingstate, the module fires a server-sidetransaction.chargeevent via thesales_order_save_afterobserver. The status in the AxiTrace admin should show “last event N minutes ago” within 1-2 minutes.
Each purchase event is idempotent. The module stores a hash of the event ID in the axitrace_event_log table with a UNIQUE constraint, so even if the observer fires more than once for the same order (e.g. on a retry), the event is never sent twice.
What gets tracked
The module fires the following events. All of them propagate to every ad platform you have connected (Facebook CAPI, TikTok Events API, Google Ads, GA4).
| Event | When it fires | Client | Server |
|---|---|---|---|
transaction.charge |
Order transitions into processing state - sales_order_save_after observer |
- | ✓ |
view_content |
Single product page loads | ✓ | - |
view_category |
Category / listing page loads | ✓ | - |
product.addToCart |
Item added to cart | ✓ | - |
begin_checkout |
Customer reaches the checkout page, with cart value/currency/item count - enabled by default | ✓ | - |
add_payment_info |
Customer reaches or selects a payment method - best-effort, enabled by default | ✓ | - |
page.view |
Every page load - disabled by default (high volume) | opt-in | - |
Storefront pixel events (product.view, product.addToCart, begin_checkout, add_payment_info) are supported on both the Luma theme and the Hyva theme. Hyva requires the separate axitrace/module-tracking-hyva package - see the section below. Enable the checkout/payment events under Stores → Configuration → AxiTrace → Events.
Hyva theme support
The Hyva theme replaces Magento’s Luma frontend with a lightweight Alpine.js + Tailwind CSS stack. Because Hyva does not include jQuery or RequireJS, the standard Luma pixel scripts cannot run.
The separate axitrace/module-tracking-hyva package (Hyva_AxiTraceTracking) ships a CSP-compatible storefront pixel built with Alpine.js. It provides the same events as the Luma pixel:
product.view,product.addToCartbegin_checkout,add_payment_info(opt-in, best-effort - see the module README for the exact trigger logic and its Hyva Checkout caveat)
Install it alongside the core module:
composer require axitrace/module-tracking-hyva && bin/magento module:enable Hyva_AxiTraceTracking && bin/magento setup:upgrade && bin/magento cache:clean
No additional configuration is needed. Once the module is enabled, it detects the Hyva theme automatically and injects the Alpine.js pixel components.
Source code: github.com/axitrace/axitrace-magento-plugin-hyva
Cookie consent
Whether tracking waits for the shopper’s cookie decision is set in AxiTrace, not in Magento: Workspace settings → Privacy & consent → Respect cookie consent. It is off by default and a change reaches your storefront within 5 minutes. The Cookie consent guide has the full picture.
In the browser: no module change needed
The AxiTrace JavaScript SDK reads Magento’s own Cookie Restriction Mode cookie,
user_allowed_save_cookie, on Luma and on Hyva alike. When the workspace switch is on, the SDK
writes nothing and sends nothing until that cookie shows a truthy entry for the current website, which is
what Magento sets when the shopper clicks Allow Cookies. If the shopper later clears that consent,
the cookie disappears and the SDK stops and deletes its own identifiers. No template edit, no module
configuration and no change to the companion axitrace/module-tracking-hyva package.
If your store uses a third-party consent platform instead of Magento’s own banner, the SDK also reads Google Consent Mode v2 and IAB TCF, and any banner can grant with one line from its accept callback:
window.axitraceConsent && window.axitraceConsent.grant();
On the server: what the purchase reports 0.2.0+
From module version 0.2.0 every purchase carries the shopper’s decision, read from the same Cookie Restriction Mode setting (Stores → Configuration → General → Web → Default Cookie Settings → Cookie Restriction Mode):
- Cookie Restriction Mode off: the order carries no consent state at all, exactly as before, and the AxiTrace workspace setting decides.
- On, and the buyer allowed cookies on this website: the order is reported as
granted. - On, and the buyer did not: the order is reported as
denied. AxiTrace still stores it, so your revenue reporting is unaffected, but it strips the advertising identifiers and forwards it to no ad platform. - Orders created outside the storefront (admin invoice, payment webhook, cron, REST API) carry no consent state rather than a wrong
denied: those requests have no buyer cookies, so a missing cookie proves nothing there.
Consent is per website: Magento writes the cookie keyed by website id, so a decision made on one website of a multi-website installation does not leak into another.
Profit tracking (product costs)
Module 0.3.0 and later can send each order line's cost from the product Cost attribute, and report credit memos and cancellations, so AxiTrace can calculate profit and POAS (Profit on Ad Spend). Set AxiTrace secret key (optional) in Stores → Configuration → AxiTrace → General to switch it on; without it no costs and no refunds are sent. Setup and details: Profit and POAS - Magento.
Visitor matching and ad click ids (0.4.0+)
From module version 0.4.0 the order remembers who placed it: when the shopper places the
order, the module stores the AxiTrace visitor and session ids, the shopper’s IP address and browser, and
every ad click id the AxiTrace SDK kept in first-party cookies (Google Ads gclid, gbraid and wbraid, TikTok
ttclid, Reddit, OpenAI Ads, and from 0.4.1 Microsoft Advertising msclkid, X twclid, Pinterest epik, LinkedIn
li_fat_id and Snapchat ScCid) on the order. The purchase sent later, when the order reaches
processing, carries them, so it is matched to the visitor’s journey and to the ad that
brought them, even when the payment is confirmed by a webhook or an invoice created in the admin. Orders
created in the admin, by cron or through the API never pick up the identifiers of whoever is logged in.
After updating run bin/magento setup:upgrade: the module adds one column to
sales_order.
Troubleshooting
Events are not arriving in the AxiTrace dashboard
Check the following in order:
- Confirm Enable AxiTrace Tracking is set to Yes and the public key is saved.
- Click Test Connection in the module configuration. If it does not turn green, verify that your server can reach
stat.axitrace.comoutbound on port 443 (curl -I https://stat.axitrace.com/health). - Check the module’s own log,
var/log/axitrace.log, forCRITICALlines, and Magento’svar/log/exception.logfor anyAxiTraceerror messages. - Verify the module is enabled:
bin/magento module:status AxiTrace_Tracking.
The status shows “Connected, but check your settings”
Purchases are arriving, but the last one went without product costs because AxiTrace did not accept the AxiTrace secret key (module 0.4.2+). Either the key is mistyped, was rotated, or belongs to another workspace than the public key. Copy the Secret Key of the same workspace as the public key again. The purchase itself is never lost: until the key is fixed, profit uses your default margin, and refunds are refused rather than booked into another workspace. Each occurrence is logged as CRITICAL in var/log/axitrace.log.
Checkout events are missing or the browser console reports a Content Security Policy error
Magento 2.4.7 enforces its Content Security Policy on the checkout pages. From module 0.4.2 the tracking domain and API base URL you configured are added to the storefront policy automatically. On an older module version update the module, or add your tracking domain to script-src and connect-src in a csp_whitelist.xml of your theme module.
Hyva pixel is not firing
Confirm that Hyva_AxiTraceTracking is enabled:
bin/magento module:status Hyva_AxiTraceTracking
If the module shows as disabled, run:
bin/magento module:enable Hyva_AxiTraceTracking && bin/magento setup:upgrade && bin/magento cache:clean
Also confirm your store is actually running Hyva - if it uses Luma, the Hyva_AxiTraceTracking module is not needed.
No purchase event - test order not appearing in the dashboard
The transaction.charge event fires only when an order transitions into the processing state. Check:
- The test order must reach processing status (not pending or pending_payment). For cash-on-delivery, manually move the order to processing in Magento Admin → Sales → Orders.
- Check that the observer did not throw an exception:
grep AxiTrace var/log/exception.log.
Test Connection fails with “Invalid public key”
pk_live_ (or pk_test_ for a test workspace). Most often the issue is a leading or trailing whitespace character pasted along with the key. Re-copy from the AxiTrace admin → Workspace settings → Tracking & domains and paste again.
Do I need to install a separate Facebook Pixel / TikTok Pixel tag?
Source code & support
Both modules are MIT-licensed and open source:
- Core module: github.com/axitrace/axitrace-magento-plugin
- Hyva compat package: github.com/axitrace/axitrace-magento-plugin-hyva
Issues and pull requests are welcome. For direct support, email info@axitrace.com - most installs are working within 10 minutes and we will personally help if yours is not.