About evaluated service methods

Evaluated service methods provide additional information on the carriers and service methods that were evaluated but not selected as optimal for a shipment during carrier selection. Your organization can access this information in two ways:

• via a call to Shipium's API for Carrier Selection and Label Service; or
• via the Shipium Console.

Retrieve unselected carrier methods via API call

When calling the Shipium API for Carrier Selection and Label Service, you may opt to include carriers and methods that were evaluated but not selected during carrier selection in your API call response. For each carrier, the carrier name, service method, carrier account ID, total cost, estimated delivery date, and estimated delivery date in local time will be returned.

The estimatedDeliveryDate field returns the estimated delivery date in UTC, while estimatedDeliveryDateLocal expresses the same date-time in the local timezone of the destination address. Because of timezone conversion, the local date may differ from the UTC date. For example, a UTC value of 2022-12-02T03:00:00Z for a destination in Mountain Standard Time (UTC-7) converts to 2022-12-01T20:00:00 local time — shifting the displayed date back by one day.

The list of unselected carriers does not include carrier methods that were filtered out due to unavailability during the carrier selection process.

You'll need to include the field includeEvaluatedServiceMethodsInResponse with a value of TRUE to return the list of unselected carriers in the call response.

Request example

This example shows the cURL request:

curl --request POST \
  --url <<api_url>>/api/v1/shipment/carrierselection/label \
  --header 'accept: application/json' \
  --header $AUTHSTRING \
  --header 'content-type: application/json' \
  --data 'INSERT REQUEST BODY FROM BELOW'

This example shows the JavaScript Object Notation (JSON):

{
  "currencyCode": "usd",
  "generateLabel": true,
  "includeEvaluatedServiceMethodsInResponse": true,
  "labelParameters": {
    "currencyCode": "usd",
    "labelFormats": [
      "zpl"
    ],
    "eligibleForManifest": true,
    "includeLabelImagesInResponse": true
  },
  "shipmentParameters": {
    "partnerShipmentId": "myCustomPartnerShipmentId123",
    "shipiumShipmentId": "49cf130d-b297-4c12-aa7d-82ea80208fde",
    "orderedDateTime": "2019-10-29T09:12:33.123456Z",
    "shippedDateTime": "2019-11-01T12:11:33Z",
    "shipOption": "company-x-expedited-shipments",
    "referenceIdentifier": "yourCustomIdentifier",
    "testMode": true,
    "shipmentTags": [
      "fall-sale-2019"
    ],
    "destinationAddress": {
      "addressType": "residential",
      "name": "Wile E. Coyote",
      "company": "ACME",
      "street1": "123 Warehouse St.",
      "street2": "Suite 42",
      "city": "Albuquerque",
      "state": "NM",
      "countryCode": "US",
      "postalCode": "87121"
    },
    "orderItemQuantities": [
      {
        "productDetails": [
          "ormd",
          "lio"
        ],
        "productId": "PRODUCTID001",
        "quantity": 3
      }
    ],
    "packagingType": {
        "packagingMaterial": "box",
        "linearDimensions": {
            "linearUnit": "in",
            "length": 9,
            "width": 6,
            "height": 3
        },
        "packagingWeight": {
            "weight": 6.58,
            "weightUnit": "lb"
        }
    },
    "totalWeight": {
      "weight": 6.58,
      "weightUnit": "lb"
    },
    "shipFromAddress": {
      "addressType": "commercial",
      "city": "Albuquerque",
      "company": "ACME",
      "countryCode": "US",
      "name": "L. Merfudd",
      "postalCode": "87121",
      "state": "NM",
      "street1": "123 Main St.",
      "street2": "Suite 42"
    }
  }
}

Response example

This example shows a JSON response. The evaluatedServiceMethods block, located within the carrierSelection block, contains the carriers and methods that were evaluated but not selected during the carrier selection process.

{
  "carrierSelection": {
    "carrier": "ups",
    "carrierAccountId": "4be237e4-eeb2-4e8a-94ea-6db695313ca6",
    "carrierSelectionDateTime": "2020-11-19T21:08:54.305Z",
    "carrierSelectionId": "5b0514bc-3cae-4311-af44-a95e64003631",
    "partnerId": "96ddb56a-18ba-4034-a14e-3fab072478f4",
    "serviceMethodName": "ground",
    "serviceMethodUrn": "c645ea83-d161-4e28-b8cb-39bf1a620cd3:4e14aaa3-198b-4861-b658-faf51031c84c:83fe5227-a765-45b2-bc2a-cb919ddce922:1",
    "totalCost": 7.53,
    "evaluatedServiceMethods": [
      {
        "carrier": "usps",
        "serviceMethodName": "usps-ground-advantage",
        "carrierAccountId": "5db5b0cd-b965-41e2-b7a9-dd275e9825be",
        "totalCost": 8.01,
        "estimatedDeliveryDate": "2022-12-02T03:00:00Z",
        "estimatedDeliveryDateLocal": "2022-12-01T20:00:00"
      },
      {
        "carrier": "ups",
        "serviceMethodName": "ups-ground",
        "carrierAccountId": "21032683-9ae9-46d0-830c-498b6c2b99b4",
        "totalCost": 8.04,
        "estimatedDeliveryDate": "2022-12-02T03:00:00Z",
        "estimatedDeliveryDateLocal": "2022-12-01T20:00:00"
      },
      {
        "carrier": "cdl",
        "serviceMethodName": "cdl-standard",
        "carrierAccountId": "494a7a1f-50ff-4c82-bbdd-7b29230ca84b",
        "injectionDetails": {
              "requestInjectionProfileId": "cdl-injection",
              "partnerInjectionProfileId": "cdl-injection",
              "shipiumInjectionProfileId": "5aj8748a-eb35-40c1-9b3c-a9eb52fd9jjf2",
              "requestInjectionSiteId": "cdl-injection-pheonix",
              "partnerInjectionSiteId": "cdl-injection-pheonix",
              "shipiumInjectionSiteId": "9v38748a-eb35-40c1-9b3c-a9eb52fd9d12"
        },
        "totalCost": 8.12,
        "estimatedDeliveryDate": "2022-12-02T03:00:00Z",
        "estimatedDeliveryDateLocal": "2022-12-01T20:00:00"
      }
  ]
  },
  "carrierName": "ups",
  "carrierTrackingId": "1Z999AA10123456784",
  "estimatedDeliveryDate": "2022-12-02T03:00:00Z",
  "destinationAddress": {
    "addressType": "residential",
    "name": "Wile E. Coyote",
    "company": "ACME",
    "street1": "123 Warehouse St.",
    "street2": "Suite 42",
    "city": "Albuquerque",
    "state": "NM",
    "postalCode": "87121",
    "countryCode": "US"
  },
  "fulfillmentCenterId": "74065136-85c2-499b-b893-bd812ac0c00f",
  "carrierLabel": {
    "effectiveShipDateTime": "2022-11-28T03:00:00Z",
    "testMode": true,
    "carrier": "ups",
    "carrierLabelCurrency": "usd",
    "carrierLabelPrice": 7.53,
    "billableWeight": {
      "weight": 6.0,
      "weightUnit": "lb"
    },
    "carrierSelectionId": "5b0514bc-3cae-4311-af44-a95e64003631",
    "carrierServiceName": "ground",
    "carrierTrackingId": "1Z999AA10123456784",
    "carrierTrackingLink": "https://www.ups.com/track?tracknum=%2B1Z999AA10123456784",
    "documents": [
      {
        "labelExpiration": "2020-11-19T21:08:54.305Z",
        "labelFormat": "zpl",
        "labelImage": {
          "imageContents": "BASE64LOOKINGSTUFFANDWHATHAVEYOUETCETCETC",
          "imageEncoding": "base64"
        },
        "labelUrl": "https://api.shipium.com/labels/1a486afc-2ffc-4c37-928f-8d6aa014b35b.zpl"
      }
    ],
    "partnerShipmentId": "myCustomPartnerShipmentId123",
    "shipiumShipmentId": "49cf130d-b297-4c12-aa7d-82ea80208fde",
    "shipiumLabelId": "5b37704e-130e-4893-82e7-600843475bbb",
    "status": "success",
    "statusDetails": "Label created successfully"
  },
  "orderItemQuantities": [
    {
      "productDetails": [
        "lio"
      ],
      "productId": "PRODUCTID001",
      "quantity": 3
    }
  ],
  "orderedDateTime": "2019-10-29T09:12:33.123456Z",
  "packagingType": {
        "packagingMaterial": "box",
        "linearDimensions": {
            "linearUnit": "in",
            "length": 9,
            "width": 6,
            "height": 3
        },
        "packagingWeight": {
            "weight": 6.58,
            "weightUnit": "lb"
        }
  },
  "partnerShipmentId": "myCustomPartnerShipmentId123",
  "shipFromAddress": {
    "addressType": "commercial",
    "city": "Albuquerque",
    "company": "ACME",
    "countryCode": "US",
    "name": "L. Merfudd",
    "postalCode": "87121",
    "state": "NM",
    "street1": "123 Main St.",
    "street2": "Suite 42"
  },
  "shipOption": "Standard",
  "referenceIdentifier": "yourCustomIdentifier",
  "shipiumShipmentId": "0840c7a2-e6ab-4755-8aa2-9a986297ad6d",
  "shipmentTags": [
    "fall-sale-2019"
  ],
  "shippedDateTime": "2019-10-29T09:12:33.123456Z",
  "testMode": true,
  "totalWeight": {
    "weight": 6.58,
    "weightUnit": "lb"
  }
}

## Response attributes for evaluated service methods

| Response attribute | Description |
| --- | --- |
| `carrierSelection.evaluatedServiceMethods` | An optional expansion of what carrier service methods were eligible but went unselected |
| `carrierSelection.evaluatedServiceMethods.carrier` | The carrier that was used for delivering the package to your customer |
| `carrierSelection.evaluatedServiceMethods.serviceMethodName` | Name of the carrier service method selected during the carrier selection process |
| `carrierSelection.evaluatedServiceMethods.carrierAccountId` | Unique ID of the carrier account selected for shipping |
| `carrierSelection.evaluatedServiceMethods.totalCost` | Cost used for carrier selection |
| `carrierSelection.evaluatedServiceMethods.estimatedDeliveryDate` | The estimated date that the shipment will arrive at its destination |
| `carrierSelection.evaluatedServiceMethods.estimatedDeliveryDateLocal` | The estimated date that the shipment will arrive at its destination, expressed in local time at the destination address. This field is present when the destination timezone can be determined |
| `carrierSelection.evaluatedServiceMethods.injectionDetails` | Injection profile and injection site details; see [Injection](https://docs.shipium.com/docs/injection) for information about injection sites. |
| `carrierSelection.evaluatedServiceMethods.rateCurrency` | The currency of the rate for the selected carrier and service method, which also applies to `lineItems` |
| `carrierSelection.evaluatedServiceMethods.lineItems.name` | The name of the rate modification |
| `carrierSelection.evaluatedServiceMethods.lineItems.rate` | The amount of the rate modification |
| `carrierSelection.evaluatedServiceMethods.lineItems.carrierSurchargeId` | The identifier for the carrier surcharge |
| `carrierSelection.evaluatedServiceMethods.lineItems.surchargeType` | The type of surcharge for this item; a null value will result for non-surcharges. |
| `carrierSelection.evaluatedServiceMethods.lineItems.lineItemType` | The type of rate line item for this rate modification |

# Retrieve unselected carrier methods via the Shipium Console

Within the Shipium Console, you can conduct a shipment search that returns the service methods that were evaluated but not selected as optimal for a shipment. Each non-selected service method includes the reason(s) it was not selected.