How do I troubleshoot carrier tracking errors?

Occasionally, Malomo is unable to track a package. This can happen if the package was shipped with a carrier that Malomo does not currently support, if the tracking code supplied is invalid with the carrier, or if required account credentials are not shared with Malomo.

When Malomo is unable to track a package, that shipment will not register in our system and we will not receive tracking updates. Without updates from the carrier, Malomo will not trigger events and any notifications that rely on our events will not be sent to the customer.

The error code will be displayed on the order details page for the associated order, as well as on the Carrier Triage card within the Active Orders Report. While we recommend reviewing the Active Orders Report regularly to view carrier tracking errors, you may also filter the Orders list by status to find a list of all orders associated to a particular error status.

Learn more about the Active Orders Report here.

Carrier Tracking Error Statuses

Error Status	Description	Fixes
`bad_tracking_code_error`	This is an invalid tracking code with the carrier name listed.	See here.
`carrier_missing_authentication_error`	In order for tracking information to be shared with Malomo, this carrier requires the shipper’s account credentials to be registered by Malomo.	See here.
`unsupported_carrier_error`	This is not a carrier Malomo currently supports. See all supported carriers here.	See here.

How to Fix Bad Tracking Code Errors

To fix a bad_tracking_code_error, you'll need to confirm that both the carrier name and tracking code are correct. We recommend checking the carrier name first, as a majority of errors are due to oddly formatted carrier names or names that include unique identifiers from 3PLs or fulfillment software.

On the Carrier Triage card within the Active Orders Report, you’ll see a list of the carrier tracking errors sorted by carrier name and showing the number of errors we’ve received. To get a list of shipments with the bad_tracking_code_error:

Navigate to the top of the Active Orders Report.
Click on the Status filter.
Check the bad_tracking_code_error status.
Scroll down to the Shipments in Transit list. To export this list, click on the three dots on the top right of the Shipments in Transit card.

If you’ve identified a group of shipments with valid tracking codes but are listed with an incorrect carrier name, you have two potential solutions:

Carrier Mapping in Malomo

The Malomo team can internally map carrier name and tracking code formats to a specific carrier for your account. To add a carrier mapping, please email us at help@gomalomo.com or reach out to our team. We’ll work with you to identify the correct carrier mapping and add it to your account.

Once a carrier mapping has been added to your account, the new carrier name will be displayed throughout the Malomo platform and in all reporting. For example, if an original carrier name of Essentialhub Priority Mail is mapped to USPS, Malomo will display USPS throughout the platform going forward.

Correcting Fulfillment Data in Shopify

Malomo relies on the carrier name and tracking code inputs in Shopify fulfillment data. If the Shopify fulfillment data is showing the incorrect carrier name or tracking code, our system will not work properly. While our carrier mapping process should correct issues, the most foolproof way of prevention is to correct the carrier names and tracking codes within Shopify first. We recommend working with your 3PL or shipping software application to confirm that the correct carrier names are passed to Shopify.

How to Fix Carrier Authentication Errors

Many carriers now require third party tracking systems to register a shipper’s account credentials, in order to access tracking information. To fix a carrier_missing_authentication_error, you'll need to obtain the necessary credentials and share that with us. Since the credentials needed vary for each carrier, please email us at help@gomalomo.com or reach out to our team to confirm which credentials are needed for your carrier. To see which of our supported carriers require credentials, please look for the lock icon 🔒 in our Supported Carriers list.

We realize that many merchants are unable to obtain carrier credentials, since their 3PL or shipper owns the account. For this, Malomo has launched our Extended Carrier Network in June 2024, which allows us to track a majority of carriers without credentials. To learn more, see here.

How to Fix Unsupported Carrier Errors

The unsupported_carrier_error is received when a shipment uses a carrier that Malomo does not currently support. Until Malomo adds support for that carrier, here are the potential solutions:

Carrier Mapping to a Supported Carrier

Some tracking codes can be tracked with a supported carrier as well. For example, many carriers use a different carrier for first or final mile delivery and those tracking codes can also be tracked with the second carrier. To investigate if Malomo can track an unsupported carrier tracking code with one of our supported carriers, please email us at help@gomalomo.com or reach out to our team to inquire.

We realize that many merchants are unable to obtain carrier credentials, since their 3PL or shipper owns the account. For this, Malomo has launched our Extended Carrier Network in June 2024, which allows us to track a majority of carriers without credentials. To learn more, see here.

Add an Unsupported Carrier Flow to Klaviyo

For shipments that cannot be tracked with a supported carrier, we recommend adding an unsupported carrier flow to Klaviyo. This will ensure that all customers receive a shipping confirmation email. Here’s a quick way to add this flow:

In your Klaviyo Flow list, navigate to your Malomo powered Shipping Confirmation flow, which is triggered either by our Malomo: ShipmentCreated or Malomo: ShipmentUpdatedReceived metric.
Click on the three dots in the right side navigation, and click Clone.
Click Clone to this account and update the name of the new flow to indicate it is for unsupported carriers. Click Continue when done.
Change the clone trigger to Malomo: ShipmentCreatedError. Click Clone Flow.
Once the new flow shows up in your Flow list, click into the flow and hit Edit.
Click Edit Email to enter into the Klaviyo email editor.
Due to different variable formats, you’ll need to edit the variables in a few different areas:
1. If your email uses any of the variables listed in the table column on the left, please update the variable to the format in the right column.

Original Variable	New Variable for ShipmentCreatedError Metric
`{{ event.carrier_name }}`	`{{ event.shipment.carrier_name }}`
`{{ event.delivered_at }}`	`{{ event.shipment.delivered_at }}`
`{{ event.estimated_delivery_date }}`	`{{ event.shipment.estimated_delivery_date }}`
`{{ event.status }}`	`{{ event.shipment.status }}`
`{{ event.tracking_code }}`	`{{ event.shipment.tracking_code }}`

b. In the fulfilled items product block (“Items in this package”), navigate to Display and the Content Repeat section. Click Edit Repeat Rules. Copy the code below and paste it into the Repeat For section. Hit Save Changes.

CODE

event.extra.order.meta.shopify_order.fulfillments|lookup:event.shipment.tracking_code|lookup:'fulfillment_line_items'

c. Navigate to the “Track My Order” button and replace the URL with the variable below. Repeat this step wherever you originally linked to the Malomo tracking page.

CODE

{{ event.shipment.carrier_url }}

Click Save.

If you run into any issues with the above steps or are unable to get your new email to render properly, please email us at help@gomalomo.com or reach out to our team. We’ll be happy to assist with adding the unsupported carrier flow to your account.

Extended Carrier Network

In June 2024, Malomo significantly expanded our supported carrier list with the launch of our Extended Carrier Network. Along with adding many new carriers, including small regional and international carriers, our Extended Carrier Network also removes the need for credentials.

Shipments tracked with a carrier in our Extended Carrier Network will be billed at flat rate per shipment and this will be an add-on to your current monthly service fee. Merchants will be required to opt-in to the Extended Carrier Network. To opt-in to the Extended Carrier Network, please complete this form.