About carrier failover

In some cases you may have carriers that are less reliable, but who you retain because of low prices or some other advantage. We think of these as best-effort carriers.

If you want to be able to add them into your shipping mix, but you do not want them to prevent associates from shipping packages, then you can mark them as being allowed to fail over when there is an issue calling that carrier.

❗️

Warning! Dangerous feature

This feature should be used with great care. If configured and triggered, it will mean that Shipium is choosing to USE A MORE EXPENSIVE CARRIER if there is a failure on this carrier's part.

Configure a carrier to allow label failover

The Carrier Accounts documentation describes setting up a new account. The Allow Label Failover option, shown below, allows the carrier to allow label failover. This means that if the carrier was selected and can't be reached, the next-best carrier and ship method will be used. You can view the configuration and change this setting if required.

Determine that carrier failover has occurred

If a carrier failover occurs as part of Carrier and Method Selection or Carrier and Method Selection & Shipment Labels, it can be identified by an additional set of fields that are not otherwise present:

• carrierLabel.labelFailoverOccurred. If this is present and set to true, a failover has occurred.
• An additional block namedcarrierLabel.labelFailoverDetails . This contains a section called preferredCarrierSelection, which shows the carrier and method that were not selected.

Both of these are shown in this example:

{
  ...
  "carrierLabel": {
    ...
    ...
    "labelFailoverOccurred": true,
    "labelFailoverDetails": {
     ...
        "preferredCarrierSelection": {
                "carrier": "fedex",
                "carrierAccountId": "a2145a5d-ac70-4fbc-9080-9639841fe65b",
                "carrierSelectionDateTime": "2021-05-21T17:31:55.765Z",
                "carrierSelectionId": "f9b011e6-c3ec-427c-a6a2-6257b4bca940",
                "partnerId": "f62d137a-2e7a-4c32-b0ba-594a113423b8",
                "serviceMethodName": "ground",
                "serviceMethodUrn": "bd322745-a7f2-451e-a9c3-661b73422ce5",
                "totalCost": 0
       }
      ...
    }
  }
}

Understanding carrier data after failover

When you retrieve shipment data via API, you'll see two separate carrier-related objects. For an example of this response structure, see Evaluated Service Methods.

carrierSelection contains the result of the initial carrier selection process, including the originally selected carrier and service method. This object is not updated when failover occurs — it preserves a record of the original selection decision.

carrierLabel contains information about the actual label that was created, including the carrier used after any failover. When failover occurs:

• carrierLabel.status will show failover.
• carrierLabel.carrier will reflect the carrier that shipped the package.
• carrierLabel.labelFailoverOccurred will be true.
• carrierLabel.labelFailoverDetails will contain details about the preferred carrier that failed.

Because these two objects serve different purposes, carrierSelection.carrier and carrierLabel.carrier may show different values after a failover event. This is expected behavior.

To determine the actual carrier used for a shipment, always reference carrierLabel.carrier rather than carrierSelection.carrier.

Resources

📘

More information on the API responses

As with all Shipium API responses, this API follows the API Response Codes standards unless otherwise specified.

Your Shipium team member is available to help along the way. However, you might find these resources helpful:

• Terms and Definitions

• Troubleshooting Guide

• Contact Shipium Support