# 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](/docs/trackeasy). 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: ```sql 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](../magento-guides/moogento-license-file-protection.md). --- ## Other pages in this guide - [TrackEasy overview, installation and FAQs](/docs/trackeasy) - [TrackEasy: Delivery Emails, SMS and Timeline Setup](/docs/trackeasy-emails-and-sms) - [TrackEasy: Carriers, Delivery Dates and Tracking Page](/docs/trackeasy-carriers-and-delivery-dates)