AxiTrace for OpenCart
A start-to-finish walkthrough: download the free extension for your OpenCart version, upload it in the Extension Installer, paste your workspace public key, and verify the first server-side purchase lands in your AxiTrace dashboard. About ten minutes from blank to fully wired. No SSH, no OCMOD modifications to refresh and no system cron required.
axitrace.ocmod.zip.
- Before you start
- Compatibility
- Copy your workspace public key
- Download the package for your version
- SHA-256 verification
- Upload the package in the Extension Installer
- Install and configure the extension
- Place a test order
- What gets tracked
- When a purchase is sent
- Cash on delivery
- Profit tracking: secret key, cost price and refunds
- Refunds, cancellations and returns
- Cookie consent
- Excluding customer groups (B2B)
- Multistore
- Failed deliveries, retries and the cron URL
- Connection health and delivery log
- Store domain verification
- OpenCart 3: the API user and admin status changes
- Journal 3 and other themes
- Data stored in your shop and retention
- Staging and test copies of your shop
- Troubleshooting
- FAQ
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).
- An OpenCart store on OpenCart 3.0.3.x - 3.0.5.x or 4.0.2.x - 4.1.x, installed at the root of its domain (see store domain verification for shops in a subdirectory).
- An admin account allowed to install and modify extensions.
- About 10 minutes.
Compatibility
| OpenCart version | PHP | Package |
|---|---|---|
| 3.0.3.x (3.0.3.0 - 3.0.3.9) | 7.4 or later | downloads/opencart-3/axitrace.ocmod.zip |
| 3.0.4.x and 3.0.5.x | 8.1 or later | downloads/opencart-3/axitrace.ocmod.zip |
| 4.0.2.x (4.0.2.0 - 4.0.2.3) | 8.0 or later | downloads/opencart-4/axitrace.ocmod.zip |
| 4.1.x | 8.1 or later | downloads/opencart-4/axitrace.ocmod.zip |
- OpenCart 1.5, 2.x, 3.0.0 - 3.0.2 and 4.0.0 - 4.0.1 are not supported. The installer refuses PHP below 7.4 with a clear message.
- Server requirements: the PHP
curlextension and outbound HTTPS (port 443) from your server to your tracking domain. No system cron, no OCMOD modification. - Themes: the default theme, Journal 3 and any theme that keeps OpenCart’s core controllers. Purchases, add to cart and checkout events are recorded from OpenCart’s own controllers and models, not from theme markup.
Copy your workspace public key
The public key (always starts with pk_live_) identifies your AxiTrace workspace. The extension uses it for 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.
- 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.
The pk_live_ public key goes into the Public key field. The secret key (sk_live_) goes only into the optional Secret key field, and only if you use profit tracking: the extension stores it encrypted, uses it server-to-server only and never prints it in your storefront. Never paste the secret key anywhere else or share it.
Download the package for your version
There is one package per OpenCart major version. Pick the one that matches your store (the version is shown in the footer of the OpenCart admin):
- OpenCart 3: axitrace.com/downloads/opencart-3/axitrace.ocmod.zip
- OpenCart 4: axitrace.com/downloads/opencart-4/axitrace.ocmod.zip
Both packages are called axitrace.ocmod.zip. OpenCart 4 takes the extension code from the file name, so a renamed file (for example axitrace (1).ocmod.zip after a second download) installs under the wrong code and does not work. Rename it back before uploading. Do not unpack the ZIP.
SHA-256 verification
Verify the ZIP integrity before installing. The SHA-256 hash of the current release of each package is published next to it:
https://axitrace.com/downloads/opencart-3/axitrace.ocmod.zip.sha256
https://axitrace.com/downloads/opencart-4/axitrace.ocmod.zip.sha256
Verify the downloaded file with:
shasum -a 256 axitrace.ocmod.zip
The two hashes must match exactly. If they differ, delete the file and download it again.
Upload the package in the Extension Installer
- In the OpenCart admin open Extensions → Installer.
- Click Upload and select
axitrace.ocmod.zip. - OpenCart 4 only: the package appears in the list of uploaded extensions; click its green Install button.
The package contains no OCMOD modification, so there is nothing to refresh under Extensions → Modifications. To update, follow the upgrade note in the release notes (CHANGELOG.md) of the new version. Your settings, the order bookkeeping, the cost prices and the retry queue are kept as long as you do not uninstall the AxiTrace analytics extension under Extensions → Extensions: uninstalling it deletes all of its data (see data retention).
Install and configure the extension
- Open Extensions → Extensions and choose the Analytics extension type.
- Click the green Install button next to AxiTrace, then the blue Edit button. With several stores, every store has its own Edit link (see Multistore).
- Set Status to enabled.
- Paste the public key you copied in Step 1 into Public key.
- Optional: paste your secret key into Secret key to send product costs and refunds (see profit tracking).
- Click Save.
Configuration field reference
Settings are stored per store under the OpenCart setting code analytics_axitrace.
| Field | Required | Notes |
|---|---|---|
Statusanalytics_axitrace_status |
Required | Master switch. Disabled, or no public key: the extension renders nothing on the storefront and sends nothing. |
Public keyanalytics_axitrace_public_key |
Required | Your workspace public key, pk_live_ followed by 32 characters. Any other value is refused when you save. |
Secret keyanalytics_axitrace_secret_key |
Optional | Your workspace secret key (sk_live_), for product costs and refunds. Stored encrypted with a key file the extension creates in OpenCart’s storage directory. The field is always shown empty: leaving it empty keeps the saved key. |
Tracking domainanalytics_axitrace_tracking_domain |
Optional | Default stat.axitrace.com. Enter your own subdomain (for example pixel.yourstore.com) CNAME’d to stat.axitrace.com and set up in AxiTrace under Tracking & domains: the browser SDK then loads from your domain and its cookies are first-party. Host name only, no https:// and no path. IP addresses and private or loopback hosts are refused and the extension falls back to stat.axitrace.com with an error on the settings page. |
Conversion valueanalytics_axitrace_value_basis |
Optional | Which order amount is reported as the purchase value to every connected platform: order total incl. tax and shipping (default), incl. tax excl. shipping, excl. tax incl. shipping, or product revenue only. Applies to new orders only. Does not affect profit. |
Cookie consentanalytics_axitrace_consent_mode |
Optional | Off (default), Browser tracking waits for consent, or Browser tracking and server-side order events wait for consent. See Cookie consent. |
Consent cookie nameanalytics_axitrace_consent_cookie |
Optional | The cookie your consent tool sets once the visitor accepts. On OpenCart 4 the default is policy, the cookie of OpenCart’s own cookie notice. |
Purchase statusesanalytics_axitrace_purchase_statuses |
Optional | Order statuses at which an order counts as a purchase. Empty (default) follows OpenCart’s own Processing Order Status and Complete Order Status settings. See When a purchase is sent. |
Cash on delivery payment codesanalytics_axitrace_cod_codes |
Optional | Payment method codes whose orders are sent when they are placed, whatever their status. Default cod. See Cash on delivery. |
Refund statuses and Cancellation statusesanalytics_axitrace_refund_statuses, analytics_axitrace_cancel_statuses |
Optional | Defaults: Refunded, Reversed and Chargeback; Canceled, Denied, Failed, Expired and Voided. See Refunds, cancellations and returns. |
Partial refunds from Returnsanalytics_axitrace_returns_refund, analytics_axitrace_return_action_ids |
Optional | On by default: a return set to the return action Refunded is sent as a partial refund of the returned products. |
Customer groups excluded from trackinganalytics_axitrace_excluded_customer_groups |
Optional | Customers of a selected group (for example your Wholesale group) are not tracked at all. Empty by default. See Excluding customer groups. |
Debug modeanalytics_axitrace_debug |
Optional | Verbose SDK console output in the storefront. Keep it off in production. |
Place a test order
- Open your storefront in a fresh private window, so you are an anonymous visitor.
- Browse a product, add it to the cart and complete an order.
- With OpenCart’s default statuses the purchase is sent when the order is placed (status Pending or Processing). If you removed Pending from the purchase statuses, set the order to Processing in Sales → Orders.
- The order appears in Orders & journeys in your AxiTrace workspace within a few minutes, under its OpenCart order id.
Every purchase carries a deterministic event id derived from the OpenCart order id. The extension records on its side that an order was sent, so changing the status again, or back and forth, never sends a second purchase. When the browser and the server both report the same order, they carry the same event id and AxiTrace stores and forwards it once.
What gets tracked
All events propagate to every ad platform you have connected (Facebook CAPI, TikTok Events API, Google Ads, GA4).
| Event | When it fires | Client | Server |
|---|---|---|---|
transaction.charge |
The order reaches a purchase status, or is placed with a cash on delivery payment method (see when a purchase is sent) | ✓ | ✓ |
product.view |
Product page loads | ✓ | - |
product.addToCart |
OpenCart adds a product to the cart (product page, listing or quick view of any theme) | ✓ | - |
begin_checkout |
The checkout page opens | ✓ | - |
add_payment_info |
A payment method is chosen in checkout | ✓ | - |
page.view |
Every page load | ✓ | - |
Client-side events are fired by the AxiTrace browser SDK, which the extension loads in the page header, and forwarded server-side by AxiTrace. Add to cart, checkout and payment events are recorded by OpenCart’s own controllers on your server and handed to the browser through a small uncached status URL (index.php?route=extension/axitrace/status), so they do not depend on your theme’s buttons or JavaScript. The extension never pushes to your dataLayer, so your own Google Tag Manager tags do not fire twice. The server-side transaction.charge is sent by the extension from your server and is not affected by ad blockers or iOS privacy restrictions.
Meta browser events and deduplication
When the Meta Pixel is present on the page, the AxiTrace SDK sends every client-side event to Meta twice on purpose: once through the browser pixel and once server-side through the Conversions API, both with the same event id, so Meta counts each event once. Load the Meta Pixel base code with fbq('init', 'YOUR_PIXEL_ID') only and remove your own PageView, ViewContent, AddToCart, InitiateCheckout and Purchase calls (including those of another analytics extension): a hand-written call carries no shared event id and is counted twice. The settings page warns you when it finds other tracking tags on your storefront.
When a purchase is sent
OpenCart has no separate “paid” flag: an order counts as a sale when it reaches one of the statuses in OpenCart’s Processing Order Status and Complete Order Status settings (System → Settings → Option). The extension follows those settings, read live, and sends the purchase once, the first time the order reaches one of them:
| Payment | Purchase is sent |
|---|---|
| Online payment (card, PayPal, payment gateways) | When the payment extension sets the order to its paid status, usually seconds after checkout. |
| Bank transfer, cheque and other payments confirmed by hand | With OpenCart’s default settings, when the order is placed: Pending is one of the default processing statuses. To wait for the payment instead, untick Pending under Purchase statuses; the purchase is then sent when you set the order to Processing, and keeps the original order date, so it is attributed to the visit that led to it. |
| Cash on delivery | When the order is placed (see below). |
| Canceled, Denied, Failed, Expired, Voided before it was sent | Never. |
A bank transfer sent at placement that is never paid counts as revenue until you set the order to Canceled; the extension then reports a cancellation for profit (see refunds). The order confirmation page also reports the purchase from the browser, but only when the order already counts as a sale at that moment. Both paths use the same event id, so the purchase is counted once.
Cash on delivery
A cash on delivery order is sent when it is placed, based on the payment method that took it:
- Cash on delivery payment codes lists the payment method codes treated this way, separated by commas. The default is
cod, OpenCart’s own Cash On Delivery extension. - Third-party cash on delivery extensions: add their payment code. You find it on any order paid with it, or in the extension’s folder name under Extensions → Extensions → Payments.
- An order of such a method that is canceled before it was sent is never sent. One that is canceled after it was sent is reported as a cancellation for profit; nothing already sent to an ad platform is changed.
Profit tracking: secret key, cost price and refunds
With the Secret key field set, the extension also sends each order line’s purchase cost and reports refunds and cancellations, so AxiTrace can calculate profit and POAS (Profit on Ad Spend). Without it, purchases are tracked as usual, with no costs and no refunds. Where to find the key and how costs and refunds count: Profit and POAS - OpenCart.
- Cost price field: OpenCart has no purchase price of its own, so the extension adds an AxiTrace cost price card at the bottom of the product form (Catalog → Products → Edit). Enter the cost in your store’s default currency.
- Option adjustments: for products with options (size, colour), each option value can add to or subtract from the product cost. A line’s cost is the product cost plus the adjustments of the options the customer chose, converted into the order currency. On OpenCart 4, variant products are separate products with their own cost price.
- A product without a cost price is sent without one, never as 0.
- Copied products do not inherit the cost price: OpenCart’s Copy button bypasses the events the extension listens to. Enter the cost on the copy.
- If the encryption key file cannot be written or read (for example after moving the shop without its storage directory), the settings page shows a banner and asks you to enter the secret key again; until then purchases are sent without costs and no refunds are sent. Tracking continues.
- If AxiTrace refuses the secret key, the purchase is sent again without costs and the settings page shows Secret key rejected.
Refunds, cancellations and returns
- Refund statuses (default Refunded, Reversed, Chargeback): an order that was sent and then reaches one of them is reported as a full refund of what was not refunded yet.
- Cancellation statuses (default Canceled, Denied, Failed, Expired, Voided): the same refund, marked as a cancellation. Refund and cancellation statuses always win over purchase statuses.
- Returns: a return (Sales → Returns) set to the return action Refunded is reported as a partial refund of the returned products (unit price incl. tax times the returned quantity). A later Refunded status refunds only the rest.
- All amounts are gross, in the order currency. Refunds need the secret key and are for profit only: they never reach Meta, Google Ads or any other ad platform, and revenue and ROAS do not change.
- Editing an order in the admin after it was sent, and deleting it, does not change what was sent.
Cookie consent
This section covers the OpenCart-specific settings. For the workspace-level forwarding policy, consent platforms and how to verify a gate actually works, see the Cookie consent guide.
On OpenCart 4, when a Cookie Policy page is selected under System → Settings → Option,
OpenCart shows its own cookie notice. The extension always respects it: the AxiTrace SDK sets no
cookie and sends no request until the visitor clicks agree (cookie policy), and starts right after
that click, without a reload. OpenCart 3 has no cookie notice of its own; use a consent tool and the setting below.
What the Cookie consent setting changes
| Setting | Browser SDK | Server-side order events |
|---|---|---|
| Off (default) | loads at once (after the OpenCart 4 cookie notice when it is active) | always sent |
| Browser tracking waits for consent | waits for consent | always sent |
| Browser tracking and server-side order events wait for consent | waits for consent | sent only when the shopper consented |
With the strictest setting, orders with no recorded consent (for example orders created in the admin) are not sent: a missing decision is never treated as a grant. Workspace settings → Privacy & consent → Respect cookie consent in AxiTrace applies on top: the extension can tighten the workspace policy, never loosen it.
How a consent grant is detected
- A consent cookie: set Consent cookie name to the cookie your consent tool sets on accept. A short poll picks the cookie up within about 500 ms.
- The JavaScript API: one line from your consent tool’s “on accept” callback:
window.axitraceConsent && window.axitraceConsent.grant();
Withdrawal, whatever the setting, stops the SDK and deletes the identifiers it wrote:
window.axitraceConsent && window.axitraceConsent.revoke();
Excluding customer groups (B2B)
When the same shop also serves customers you do not want in your marketing data, typically wholesale buyers, select their group under Customer groups excluded from tracking (per store):
- Purchases, refunds and cancellations of their orders are not sent.
- Browsing while logged in: the AxiTrace script does not start. Pages viewed before logging in are collected as an anonymous visit; they contain no order, so they never create a conversion.
- Page cache: the decision is never written into the page HTML. Before the script loads, the storefront asks the uncached status URL whether the current customer may be tracked.
- Other tags (your own Google Tag Manager container, another extension’s pixel) are not affected and need their own exclusion.
Multistore
OpenCart lists every store next to the AxiTrace analytics extension with its own Edit link, and each store has its own settings:
- Each store can have its own public key, so each store can report to its own AxiTrace workspace. One workspace per store is recommended when the stores sell under different domains or currencies.
- Every order is sent with the settings of the store it was placed in, including retries and refunds sent later.
- Cost prices are per product, shared by every store.
Failed deliveries, retries and the cron URL
The extension sends a purchase the moment the order status changes, with a short timeout so your admin and checkout never wait for AxiTrace. If AxiTrace cannot be reached, the purchase is kept in a queue in your shop database, with the same event id, and sent again later:
- Retries start after 5 minutes and wait twice as long each time, up to 6 hours between attempts, for at most 10 attempts. After that the entry is marked failed and kept for 30 days in the delivery log.
- The secret key is never stored in the queue; it is read from the settings at each attempt.
- No cron is required. Due retries run in small batches at the end of ordinary storefront and admin requests, after the response was sent to the visitor.
- Optional cron URL: on a quiet shop, retries may wait until the next visit. The settings page shows a Cron URL with a copy button; call it every 5 to 15 minutes from your hosting panel’s cron or any uptime monitor. It looks like:
The token is generated when the extension is installed; a wrong token is refused withhttps://your-shop.com/index.php?route=extension/axitrace/cron&token=<your token>403.
Connection health and delivery log
The extension’s settings page shows:
- Connection health: the last successful delivery, the last failure, whether product costs are accepted, the store domain verification status, whether the OpenCart 4 cookie policy is active, the extension, OpenCart and PHP versions, and a banner when the public key or the secret key was rejected or the secret key has to be entered again.
- Other tags detected: other enabled analytics extensions and tracking tags (Google tag, Google Tag Manager, Meta Pixel, TikTok Pixel) found on your storefront, which may count events twice.
- Delivery log: the last 50 queued and failed deliveries with event id, type (purchase or refund), attempts and last error. Retry now sends the queued entries immediately.
Store domain verification
AxiTrace only accepts events from domains your workspace knows. The extension asks AxiTrace to verify your store’s domain by itself when you save the settings and once a day: AxiTrace fetches a one-time proof from index.php?route=extension/axitrace/proof on your store and adds the domain to the workspace. This needs the secret key. A store installed in a subdirectory (for example example.com/shop/) cannot be verified automatically: the settings page says Auto-verification needs the store at the root of its domain; tracking keeps working once you add the domain by hand under Tracking & domains. See Domain configuration.
OpenCart 3: the API user and admin status changes
On OpenCart 3, changing an order status in the admin goes through OpenCart’s own API (System → Users → API). If your IP address is not on the API user’s IP list, OpenCart refuses the change with a warning and nothing is sent, because the status was never changed. Add your IP address under the IP Addresses tab of the Default API user. OpenCart 4 changes statuses without that API, so no setup is needed there.
Journal 3 and other themes
- Quick Checkout: the server-side purchase is recorded from OpenCart’s order history, so it is sent whatever checkout the theme uses. A one-page checkout that never shows the success page sends no browser purchase; the server purchase still arrives.
- JS Combine and Defer (Journal performance settings) are supported: the extension’s script runs on its own and does not depend on jQuery.
- Custom Code: do not paste a second AxiTrace snippet into Journal’s Custom Code or Google Tag Manager; the extension already loads the SDK and a second copy counts events twice.
- A theme whose header does not call OpenCart’s analytics extensions is covered too: the extension inserts its block into the page header once, never twice.
Data stored in your shop and retention
For every order the extension stores an attribution snapshot in its own table: visitor and session ids, ad click ids, the Meta and Google cookies, the consent decision, the IP address, the user agent and the landing page. It is used only to send that order’s purchase.
- The IP address, user agent, cookie ids and click ids are blanked 30 days after the purchase was sent or the order was skipped. The order id and the fact that it was sent are kept, so a later status change never sends the order again.
- Snapshots of checkouts that never became an order, and failed deliveries, are deleted after 30 days.
- OpenCart’s own GDPR export and erasure requests are not connected to the extension in this version; the 30-day blanking covers the personal data it stores.
- Uninstalling the analytics extension deletes its tables, its settings for every store and its encryption key file.
Data already received by AxiTrace is handled by AxiTrace; see our privacy policy.
Staging and test copies of your shop
A staging or test copy of your shop numbers its orders independently, so it produces the same order ids as your live shop. AxiTrace identifies a purchase by its order id, so a test order sent to your live workspace can block the real order with the same id, or the other way round. Create a separate AxiTrace workspace for each staging or test copy and put its public key into that copy’s settings. When you copy your live database to staging, change the key there before placing any order.
Troubleshooting
Events are not arriving in the AxiTrace dashboard
Check the following in order:
- Status is enabled and the Public key is saved for the store you test (each store has its own Edit link).
- The page source of your storefront contains
axitrace-opencart-config. If not, refresh the theme cache with the gear button on the admin Dashboard (and Journal’s own cache, if you use Journal) and reload. - Your storefront domain is verified or added under Tracking & domains (see store domain verification).
- Your server can reach your tracking domain on port 443:
curl -I https://stat.axitrace.com/health. - The connection health and delivery log on the extension’s settings page, and System → Maintenance → Error Logs filtered by
axitrace.
No purchase for a test order
- The order must reach a status in Purchase statuses (by default OpenCart’s processing and complete statuses).
- A cash on delivery order is sent at once only if its payment code is listed in Cash on delivery payment codes.
- On OpenCart 3, an admin status change refused by the API user’s IP list changes nothing (see above).
- The customer’s group is not in Customer groups excluded from tracking.
- With the strictest Cookie consent setting, the shopper must have accepted cookies.
- A failed delivery is retried automatically; see the delivery log.
The extension installs under a strange name on OpenCart 4
axitrace (1).ocmod.zip). Uninstall and delete that package in Extensions → Installer, rename the file to axitrace.ocmod.zip and upload it again.
The public key is refused when I save
pk_live_ followed by 32 characters. The most common cause is a space pasted along with the key. Copy it again from Workspace settings → Tracking & domains in AxiTrace.
Do I need a separate Facebook Pixel or TikTok Pixel extension?
FAQ
Which OpenCart versions are supported?
Does it change OpenCart’s files?
Does the extension import past orders?
Is the extension free?
Source code & support
The extension is open source under the GNU General Public License v3.0 or later (GPL-3.0-or-later):
Issues and pull requests are welcome. For direct support, email info@axitrace.com - we will personally help if your install is not working.