# 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 Contracts](https://docs.shipium.com/docs/carrier-contracts#carrier-settings) documentation describes setting up a carrier contract, including the **Carrier Settings** section where label failover is configured. The **Allow Label Failover** option, shown below, is a required True/False dropdown within Carrier Settings. When set to **True**, label failover is allowed. If the selected carrier 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 by selecting **Edit** in the Carrier Settings section.

# Determine that carrier failover has occurred

If a carrier failover occurs as part of [Carrier and Method Selection](https://docs.shipium.com/docs/carrier-and-method-selection) or [Carrier and Method Selection & Shipment Labels](https://docs.shipium.com/docs/carrier-method-selection-label-single-call), 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 named `carrierLabel.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:

JSON

```json
{
  "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](https://docs.shipium.com/docs/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.
- `carrierLabel.laneMatch` will reflect the lane associated with the carrier that shipped the package, if you use [shipment lanes](https://docs.shipium.com/docs/shipment-lanes).

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`.**

# FAQ

**Q:** Why do `carrierSelection.laneMatch` and `carrierLabel.laneMatch` show different lanes?

**A:** `carrierSelection.laneMatch` reports the lane chosen during the initial carrier selection, and it is not updated when failover occurs. `carrierLabel.laneMatch` reports the lane for the label that was actually created. On a shipment that ships on its originally selected carrier, both report the same lane. When a label failover sends the shipment to a different carrier, `carrierSelection.laneMatch` continues to report the original lane while `carrierLabel.laneMatch` reports the lane associated with the carrier that shipped the package. To determine the lane the printed label belongs to, reference `carrierLabel.laneMatch`. For where these fields appear in the response and their attributes, see [Shipment Lanes](https://docs.shipium.com/docs/shipment-lanes).

# Resources

> 📘
>
> ### More information on the API responses
>
> As with all Shipium API responses, this API follows the [API Response Codes](https://docs.shipium.com/docs/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](https://docs.shipium.com/docs/common-terms)
- [Troubleshooting Guide](https://docs.shipium.com/docs/troubleshooting-guide)
- [Contact Shipium Support](https://docs.shipium.com/docs/contacting-shipium-support)