Toggle Nav
Menu
Currency
USD
Customer account avatar
My Cart
TrackEasy · By Sophie Calder · Updated 4 Nov 2026 · 13 min read

TrackEasy: Reference, Tips and Troubleshooting

Feature reference, advanced configuration, best practices, and answers to common tracking problems.

This page is part of the TrackEasy guide. Start there for what the extension does, installation and the frequently asked questions.

Features reference

General

  • What it does: Master on/off switch for TrackEasy, plus verbose logging toggle.
  • When to use it: Disable temporarily during maintenance; enable logging only when diagnosing a problem - the log file grows quickly in production.
  • Config path: moogento_trackeasy/moo/enable and moogento_trackeasy/moo/enable_logging

Design: Orders Page

  • What it does: Renders the Delivered By Date in the admin orders grid using a calendar-page widget that matches the timeline style.
  • When to use it: Enable when your team regularly checks delivery dates from the grid view.
  • Config path: moogento_trackeasy/moo/style_dbd_in_orders

UPS: Live Calls

  • What it does: Sets the UPS API environment - sandbox (wwwcie.ups.com) or production (onlinetools.ups.com). Credentials (Access Key, Username, Password) are read from Sales > Delivery Methods > UPS.
  • When to use it: Switch to sandbox for initial testing; flip to production before going live.
  • Config path: moogento_trackeasy/carrier_ups/use_sandbox

Setup: Google Analytics

  • What it does: Configures the UTM parameters appended to the tracking links TrackEasy generates for the storefront and for emails, and to the product links on the tracking page, in both the shipment item list and the upsell block. Defaults are utm_source=trackeasy, utm_medium=upsell, utm_campaign=post_purchase. Carrier tracking links, SMS links, admin links, and the link a shopper copies with the copy control stay untagged.
  • When to use it: Change if your GA4 campaigns use a different naming convention, or if you want to attribute post-purchase revenue to a specific promotion.
  • Good to know: Leave a field blank to leave that parameter off the links entirely. Changes apply to links generated or rendered from that point on - emails already sent keep the values they were built with.
  • Config paths: moogento_trackeasy/moo/utm_source, moogento_trackeasy/moo/utm_medium, moogento_trackeasy/moo/utm_campaign

Integration: ShipEasy

  • What it does: When ShipEasy Growth or Pro is installed, this toggle allows a dbd column in a ShipEasy CSV import to bulk-update the Delivered By Date for multiple orders at once.
  • When to use it: Enable when you receive carrier-provided delivery windows in a spreadsheet and want to paste them in bulk rather than editing orders one by one.
  • Config path: moogento_trackeasy/shipeasy_integration/csv_import
  • Format the dbd column as Y-m-d (e.g. 2026-05-27).

Integration: ShipperHQ Delivery Date

  • What it does: At order placement, reads the delivery date ShipperHQ selected for the shipment and writes it into moo_trackeasy_dbd. The success-page DBD, timeline, and calendar tools then reflect the carrier's committed date rather than a generic offset.
  • When to use it: Enable when your store uses ShipperHQ for rated delivery-date promises and you want those dates to flow through to TrackEasy automatically. Requires a Pro license.
  • Config path: moogento_trackeasy/shipperhq_bridge/enabled
  • Set Overwrite existing DBD (moogento_trackeasy/shipperhq_bridge/overwrite_existing_dbd) = Yes only if you want the ShipperHQ date to replace any DBD already saved on the order.

Integration: ShipStation Delivery Date

  • What it does: At order placement, calls the ShipStation v2 Rate API with the order's shipping method and address, retrieves the estimated_delivery_date, and writes it into moo_trackeasy_dbd. Sets an API-sourced delivery estimate the moment an order is placed, before any carrier scan events arrive.
  • When to use it: Enable when you fulfil through ShipStation and want the most accurate delivery estimate available at order time. Requires a Pro license.
  • Config path: moogento_trackeasy/shipstation_bridge/enabled
  • Key supporting fields:
    • ShipStation API Key (moogento_trackeasy/shipstation_bridge/api_key) - your ShipStation v2 API key
    • API timeout (seconds) (moogento_trackeasy/shipstation_bridge/timeout_seconds) - default 2; keep low to minimise impact on order placement time
    • Overwrite existing DBD (moogento_trackeasy/shipstation_bridge/overwrite_existing_dbd) - when enabled, replaces any existing DBD
    • Service code overrides (moogento_trackeasy/shipstation_bridge/service_code_overrides) - map Magento shipping methods to ShipStation service codes, one per line (e.g. flatrate_flatrate=usps_priority_mail)

Integration: ProfitEasy order source card

  • What it does: On the admin order view, when ProfitEasy is installed, enabled and on a Pro licence, TrackEasy adds facts to ProfitEasy's "How TrackEasy probably helped" card: the tracking-page interaction that led back to the store, the latest earlier order on the same logged-in customer account (guests are not matched), and - on a Pro TrackEasy licence - whether a shipment SMS about that earlier order was sent or delivered before the interaction.
  • When to use it: No setup needed beyond having both modules installed, enabled and on a Pro ProfitEasy licence; the card only appears on orders with a recorded tracking-page interaction.
  • Requires: ProfitEasy installed, enabled and on a Pro licence. Only ProfitEasy Pro shows the Sale Source panel. The card is facts-only and never claims a purchase was caused by a tracking-page visit, only that the two are likely related.

Advanced configuration

Timeline image - PNG vs SVG embed modes

What it does

TrackEasy can embed the delivery timeline in emails as a PNG image or as inline SVG code. PNG is the safe default - every email client renders it. SVG is crisper at all sizes and smaller in bytes, but a small number of older email clients may not render it.

Setup

  1. Go to: Stores > Configuration > Moogento > TrackEasy > Setup: Emails > Emails: Timeline Image > Embed Mode

  2. Set Embed Mode to PNG or SVG.

  3. For PNG, check the status indicator:

    • Green - rsvg-convert (librsvg) detected: best quality.
    • Orange - Imagick available but rsvg-convert missing: fallback quality.
    • Red - Imagick not installed: PNG generation unavailable; emails fall back to inline SVG or text.

  4. Install rsvg-convert on the server if you want the highest-quality PNG output:

    • Ubuntu/Debian: sudo apt-get install librsvg2-bin
    • CentOS/RHEL: sudo yum install librsvg2-tools

Notes

  • If both rsvg-convert and Imagick are unavailable, format="png" and format="svg" timelines are replaced by the html timeline, so emails never contain a broken picture.

Carrier refresh queue and cron schedule

What it does

Carrier polling runs asynchronously via Magento's message queue. The moogento_trackeasy_enqueue_track_refresh cron job (every 10 minutes) pushes the parcels that are due for a check into the moogento_trackeasy_carrier_refresh queue. A queue consumer processes each record, calls the carrier API, and writes results to moo_trackeasy_track_cache.

Setup

  1. Confirm the Magento default cron group is running on your server.

  2. Confirm the message queue consumer is running (or that Magento's DB broker is configured for async processing).

  3. Check the cache table for problems:

    SELECT tracking_number, status, error_message, next_attempt_at
FROM moo_trackeasy_track_cache
WHERE error_message IS NOT NULL
ORDER BY next_attempt_at DESC
LIMIT 20;

Notes

  • Failed calls are retried with exponential back-off using the next_attempt_at field.
  • Verbose logging to var/log/moogento_trackeasy.log can be enabled at Stores > Configuration > Moogento > TrackEasy > General > Enable Logging while diagnosing queue problems. Disable it again in production.

ShipperHQ Delivery Date Bridge

What it does

Reads the ShipperHQ-selected delivery date from Magento order and quote tables at order placement and writes it into moo_trackeasy_dbd. Three events are observed (sales_order_place_after, checkout_onepage_controller_success_action, checkout_submit_all_after). Each attempt is idempotent. Requires a Pro license.

Setup

  1. Ensure the ShipperHQ_Shipper module is installed and php bin/magento setup:upgrade has been run.
  2. Go to: Stores > Configuration > Moogento > TrackEasy > Integration: ShipperHQ Delivery Date
  3. Set Enable = Yes.
  4. Set Overwrite existing DBD = Yes only if the ShipperHQ date should replace a DBD already saved on an order.
  5. Save Config and run php bin/magento cache:clean.

Notes

  • The bridge never calls the ShipperHQ GraphQL Rates API - it only queries Magento-local ShipperHQ tables.
  • For split-shipment orders, the latest valid date across all ShipperHQ rows for the order is used.
  • Config paths: moogento_trackeasy/shipperhq_bridge/enabled, moogento_trackeasy/shipperhq_bridge/overwrite_existing_dbd

ShipStation Delivery Date Bridge

What it does

Calls the ShipStation v2 Rate API at order placement and writes the returned estimated_delivery_date into moo_trackeasy_dbd. The call is synchronous with a short configurable timeout (default 2 seconds) to minimise impact on checkout. Requires a Pro license.

Setup

  1. Go to: Stores > Configuration > Moogento > TrackEasy > Integration: ShipStation Delivery Date
  2. Set Enable = Yes.
  3. Enter your ShipStation API Key (from your ShipStation account settings).
  4. Adjust API timeout (seconds) if needed - keep it at 2 or lower for production.
  5. Configure Service code overrides if Magento shipping method codes do not map automatically to ShipStation service codes.
  6. Save Config and run php bin/magento cache:clean.

Notes

  • The carrier list fetched from /v2/carriers is cached for 24 hours by default (configurable via Carrier list cache duration (hours) = moogento_trackeasy/shipstation_bridge/carrier_cache_hours).
  • ShipStation v2 authentication uses a single API-Key request header, not a Bearer token.
  • If no estimate is returned, TrackEasy's existing DBD calculation behaviour remains in place.
  • Config paths: moogento_trackeasy/shipstation_bridge/enabled, moogento_trackeasy/shipstation_bridge/api_key, moogento_trackeasy/shipstation_bridge/timeout_seconds, moogento_trackeasy/shipstation_bridge/service_code_overrides

Tips & best practices

  • Start carrier connections in sandbox mode. Only switch to production credentials once a live tracking number returns events in the Test API tool.
  • Enable DBD updates from the carrier API (moogento_trackeasy/moo/auto_set_dbd_on_api_response = Yes) so your customers always see the most current delivery estimate rather than the original order-date offset.
  • If your store ships only to one country, set the Hide this 'country name' field on the tracking page to keep the address block clean.
  • Keep verbose logging off in production. Turn it on, reproduce the issue, then turn it off again - the log file has no automatic size limit.
  • For the upsell block, configure a minimum-price filter to avoid recommending products that are cheaper than or similar in value to what the customer already ordered.
  • If you use ShipEasy for admin order processing, enable the ShipEasy CSV import integration so bulk DBD updates from carrier manifests flow through without manual editing.
  • The media/trackeasy/ directory must be writable and have at least 100 MB free - timeline image generation is skipped silently when disk space is low.
  • For the most accurate order-time delivery estimates, choose one DBD source: ShipperHQ bridge (if you use ShipperHQ), ShipStation bridge (if you fulfil via ShipStation), or the carrier API offset calculation. Running multiple bridges at once is safe but the last write wins unless Overwrite existing DBD is off on the later bridges.

Troubleshooting

Carrier API calls return no tracking events

Carrier credentials are saved but no tracking events appear on the tracking page or in the orders grid.

  • Cause: Credentials may be incorrect, the API may be set to sandbox when production is needed (or vice versa), or the carrier requires IP allow-listing.
  • Check: Go to Stores > Configuration > Moogento > TrackEasy > Setup: Carrier Tracking APIs and use the Test button. Also inspect var/log/moogento_trackeasy.log and the moo_trackeasy_track_cache table for messages.
  • Resolution: Re-enter credentials carefully (no leading or trailing spaces). For FedEx, confirm the OAuth app has the Tracking API enabled in the FedEx Developer Portal. For UPS, confirm you have a Legacy Access Key - new OAuth-only credentials do not work. Switch sandbox/production environment to match the tracking number you are testing with.

DBD is not updating from carrier data

The Delivered By Date in the orders grid shows the original estimate, or the order stays on "(Pending)", and never changes even after carrier scans occur.

  • Cause: One of several things can stop a carrier-confirmed date from reaching an order: the Update DBD based on shipper API response setting is disabled; Magento cron isn't running; the message queue consumers aren't running (this is what actually calls the carrier API - the cron job below only adds tracking numbers to the queue); the carrier credentials aren't set at the order's store view (a value saved only at Default Config doesn't apply to a store that has its own scope); the carrier type doesn't provide a delivery estimate (Royal Mail and Evri are link-only and don't return ETA data); or, for UPS specifically, the sandbox toggle was never touched - an untouched UPS API Environment setting behaves as sandbox and returns no live data even with valid production credentials.
  • Check:
    1. Verify moogento_trackeasy/moo/auto_set_dbd_on_api_response = Yes.
    2. Confirm Magento cron is running: bin/magento cron:run --group=default should complete without errors, and cron_schedule should show recent moogento_trackeasy_enqueue_track_refresh runs. This job only queues tracking numbers for a refresh - it does not call the carrier API itself.
    3. Confirm the queue consumer that does the actual carrier lookups is running: bin/magento queue:consumers:list should show moogento_trackeasy_carrier_refresh_consumer, and it needs to be started by your server's cron consumers runner (or a supervisor process) to process messages continuously.
    4. If the store has more than one store view, check that carrier credentials at Stores > Configuration > Moogento > TrackEasy > Setup: Carrier Tracking APIs are set (or inherited) at the order's own store view, not only at Default Config.
    5. For UPS, confirm UPS API Environment at Stores > Configuration > Moogento > TrackEasy > UPS: Live Calls is explicitly set to Production - leaving it untouched keeps it in sandbox mode.
  • Resolution: Enable the API DBD update setting, get cron and the queue consumer both running continuously, set carrier credentials at the correct store scope, and explicitly switch UPS out of sandbox mode. While you sort out the underlying cause, use the Refresh tracking events button on the order's TrackEasy timeline in admin to fetch a carrier update for that one order immediately.

Timeline shows as html instead of a picture

A format="png" or format="svg" timeline shows as the html timeline.

  • Cause: rsvg-convert and Imagick are both unavailable, the rasteriser took longer than 5 seconds, the media/trackeasy/timeline/ directory is not writable, or media is stored in the database.
  • Check: Review var/log/moogento_trackeasy.log for one [Rasterizer::rasterize] or [ImageOutput::render] warning.
  • Resolution: Install librsvg2-bin (Ubuntu) or librsvg2-tools (CentOS) and restart PHP-FPM. The html timeline needs nothing extra.

Tracking page returns 404

The tracking URL sent to a customer returns a 404 page.

  • Cause: URL rewrites are disabled, the module is not enabled, or the cron that assigns tracking tokens to orders has not run yet for recent orders.
  • Check: Run bin/magento module:status Moogento_Trackeasy and verify URL rewrites are on (web/seo/use_rewrites = 1). For new orders, run bin/magento moogento:trackeasy:order:ensure-code to generate tokens immediately.
  • Resolution: Enable URL rewrites and run php bin/magento cache:clean. For a single order, use the CLI command to assign a token manually.

No cross-sell products appear on the tracking page

The upsell block is enabled but the tracking page shows no product recommendations.

  • Cause: No products meet all the display criteria (enabled, in stock, has image, visible in catalog/search), cross-sell relationships are not set on the ordered products, and the random fallback is disabled.
  • Check: Confirm Enable = Yes under Stores > Configuration > Moogento > TrackEasy > Design: Tracking Pages > Add: Upsell/Custom Block. Check whether Crosssell block: If empty slots, show random products? is set to Yes.
  • Resolution: Either configure cross-sell relationships on the products being purchased, reduce the minimum-price filter, or enable random fallback to fill slots with in-stock products.

DBD not set after order placement via ShipperHQ or ShipStation bridge

The Delivered By Date is still showing a calculated offset after orders are placed, even though a bridge is enabled.

  • Cause: The bridge is disabled, the license is not Pro, the third-party module (ShipperHQ or ShipStation) is not installed, or no delivery date data was returned.
  • Check: Review var/log/moogento_trackeasy.log for messages about disabled config, invalid license, missing module tables, or empty API responses. For ShipperHQ, confirm ShipperHQ_Shipper is installed. For ShipStation, confirm the API Key is correct and the shipping method maps to a ShipStation service code.
  • Resolution: Verify the Enable toggle is on at the relevant Integration section, confirm a Pro license is active, and ensure the third-party integration is fully installed and configured. For ShipStation, add a service code override entry if the Magento shipping method code is not recognised automatically.

Malware scanner flags Helper/Moo.php

  • Cause: Your host's malware scanner (often Imunify360 on cPanel hosting) heuristically flags the encoded license-check files that ship inside every paid Moogento extension. The files are genuine and unchanged - the encoding protects the license check from tampering.
  • Resolution: Add the files to the scanner's ignore list so the warnings stop, and restore any file the scanner already quarantined. Both steps, plus how to verify the files are byte-for-byte what we shipped, are covered in the license file protection guide.

Other pages in this guide