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 application programming interface (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, and estimated delivery date will be returned.

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 '{"currencyCode": "usd", "generateLabel": true, "labelParameters": {"testMode": true,"currencyCode": "usd", "labelFormats": ["ZPL"], "manifest": 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": "Standard", "shipmentTags": ["string"], "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": {"packagingTypeId": "cf3daf7d-6fca-46c2-9d9e-30a476dcc1e4"}, "totalWeight": {"weight": 6.58, "weightUnit": "lb"}, "shipFromAddress": {"addressType": "commercial", "city": "Albuquerque", "company": "ACME", "countryCode": "US", "name": "Wile E. Coyote", "postalCode": "87121", "state": "NM", "street1": "123 Main St.", "street2": "Suite 42"}}}'
POST /api/v2/shipment/carrierselection/label

This example shows the JavaScript Object Notation (JSON):

{
  "currencyCode": "usd",
  "generateLabel": true,
  "includeEvaluatedServiceMethodsInResponse": true, <== EXAMPLE
  "labelParameters": {
    "testMode": true,
    "currencyCode": "usd",
    "labelFormats": [
      "ZPL"
    ],
    "manifest": 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",
    "shipmentTags": [
      "string"
    ],
    "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. Note that the third element of the array in the example demonstrates use of an injection site.

{
  "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"
      },
      {
        "carrier": "ups",
        "serviceMethodName": "ups-ground",
        "carrierAccountId": "21032683-9ae9-46d0-830c-498b6c2b99b4",
        "totalCost": 8.04,
        "estimatedDeliveryDate": "2022-12-02T03:00:00Z"
      },
      {
        "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"
      }
  ],
  },
  "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",
    "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": "string"
      }
    ],
    "partnerShipmentId": "myCustomPartnerShipmentId123",
    "shipiumShipmentId": "49cf130d-b297-4c12-aa7d-82ea80208fde",
    "shipiumLabelId": "5b37704e-130e-4893-82e7-600843475bbb",
    "status": "success",
    "statusDetails": "Label created successfully"
  },
  "orderItemQuantities": [
    {
      "productDetails": [
        "string"
      ],
      "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"
    "countryCode": "US"
  },
  "shipOption": "Standard",
  "referenceIdentifier": "yourCustomIdentifier",
  "shipiumShipmentId": "0840c7a2-e6ab-4755-8aa2-9a986297ad6d",
  "shipmentTags": [
    "string"
  ],
  "shippedDateTime": "2019-10-29T09:12:33.123456Z",
  "totalWeight": {
    "weight": 6.58,
    "weightUnit": "lb"
  }
}

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.

To access the shipment search details, you’ll first need to log in to the Shipium Console. Within the console, you’ll select Delivery Reporting → Shipment Search from the lefthand navigation menu.

Within Shipment Search, you can use the search bar for a simple search by shipment ID or other property, or you can select Advanced Search.

Search

Fields that can narrow your simple search include the:

date range of your shipment search;
fulfillment center, which you will select from a dropdown menu (you may choose All or a particular fulfillment center);
tenant, which you will select from a dropdown menu (you may choose All or a particular tenant); and
label filter, which you will select from a dropdown menu (ONLY Shipments with Labels, ONLY Carrier Selections without Labels, or All Shipments).

Advanced search

You can use the advanced search parameters to narrow your search results.

For an advanced search, you can populate the following fields to filter your search results:

Shipment ID. The Shipium shipment identifier
Shipium Label ID. An identifier passed to Shipium representing your organization’s shipment identifier
Carrier. The applicable carrier, which you'll select from a dropdown menu
Shipment Tag. Any tag value you passed in the API request body
Label Statuses. The label status of your shipment, which you'll select from a dropdown menu. Status values include Success, Success Generated, Success Created, Success Manifested, Success Failover, Success Voided, Failure, and Success Manifest Failure.
Tracking Statuses. The tracking status of your shipment, which you'll select from a dropdown menu. Status values include Info Received, Picked Up, Arrived at Carrier Facility, Departed Carrier Facility, In Transit, Out for Delivery, Delivered, Hold, Exception, and Unknown.
Hazmat. You'll select the hazmat value from a dropdown menu. If the shipment contained hazardous materials, this value is True; if it did not contain hazardous materials, this value is False.
Destination Postal Code. The United States Postal Service postal code of the destination address
Destination Country. The country of the destination address, which you'll select from a dropdown menu
Custom Label Key. A string value serving as a key for a custom label value included in the API request body, with the custom label value represented by the key to be printed on the label
Custom Label Value. A string representing a custom label value passed in the API request body on label creation
Exclude Test Mode. You'll select the test mode value from a dropdown menu. If the shipment was generated in test mode, this value is True; if it was not generated in test mode, this value is False.

For additional guidance, you can select Supported Search Terms, which displays the search terms with explanations, as shown in the following screenshot.

Field definitions for simple and advanced search results

This section lists terms and descriptions associated with shipment search details within the Shipium platform. They are organized by the search detail categories that appear on the shipment search results screen:

Request details

Information provided in the Request Details section includes the address from which the package was shipped and the address to which the package was shipped. Shipment details are also returned for a shipment search, including the type of shipment, the package's dimensions and weights, the desired delivery date, the shipped date timestamp, and other special shipping properties.

By toggling the carat next to API Request Body, you also can view the JSON request body for the API call.

Term	Description
Ship-From	The address from which the package was shipped. The address is part of origin configuration.
Shipment Details	Details of the shipment, to follow:
Type	The type of package. This value can be: - Box - Envelope - Flat Pack
Dimensions	Physical dimensions of the package
Billable Weight	The weight used on the rate table to select an estimated cost. The physical weight is configured by the carrier and is typically rounded up. Dimensional weight will be displayed if used for rate selection.
Dim (Dimensional) Weight	Dim weight is the amount of space a package occupies in relation to its actual weight, as defined by the carrier. This value is typically Length (l) x Width (w) x Height (h) / dim weight divisor.
Physical Weight	The physical weight of the package included in the API request body
Delivery Signature Option	- If the option was not included in the API request body, the value is None. - If the option was included in the API request body, values for the type of signature include: - signature - resident signature - adult signature - adult resident signature
Saturday Delivery	- If Saturday delivery was included in the API request body, the value is True. - If Saturday delivery was not included in the API request body, the value is False.
Desired Delivery Date (DDD)	The DDD provided in the API request body. It is expressed in Coordinated Universal Time (UTC) and in compliance with ISO 8601 standards.
Shipped Date Timestamp	The date the shipment left the warehouse. The Shipped Date Timestamp is expressed in UTC and in compliance with ISO 8601 standards.
Ship-To	The commercial or residential address of the package recipient
API Request Body	The API request body in JSON format

Label

The Label section includes a print preview of the shipping label along with a unique label identifier, label status, shipping price, carrier and service method for the shipment, and label properties. Shipment details are also returned for a shipment search, including the type of shipment, the package's dimensions and weights, the desired delivery date, the shipped date timestamp, and other special shipping properties.

Term	Description
Label ID	The Shipium unique label identifier
Status	The status of the shipment label. This value can be: - Success - Failed - Void
Status Detail	The status detail of the shipment label. This value can be: - Success Created - Success Failover - Success Test Mode - Failed - Void
Price	The Shipium estimated cost for the shipment, based on the carrier
Service Name	The carrier and service method for the shipment
dpi/dpmm	The resolution of the label printing: - dpi = dots per inch - dpmm = dots per millimeter
Width	The width of the label, in inches
Height	The height of the label, in inches
Orientation	The rotation applied to the label. The default value is 0 (zero).
Label Expiration	The Shipium estimated date of label expiration
Right-Side Menu	The menu options at right, to follow:
Info	The information detailed above from the primary Label screen
Label	A printing preview of the label

Shipment order items

Information in the Shipment Order Items section includes a unique product identifier for the shipment, the order quantity, any product tags assigned by your organization, and an indicator for hazardous materials in the order. This section also includes other unique identifiers for the shipment order, such as Shipium Order ID.

Term	Description
Delivery Estimate ID	A Shipium ID from the estimate provided by Delivery Promise. The default value is Not Applicable (N/A).
Shipium Order ID	A Shipium ID of a group of delivery estimates purchased, provided by Delivery Promise. The default value is N/A.
Partner Order ID	An order ID included in the API request body. The default value is N/A.
Product ID	The product ID passed in the API request body
Quantity	The number of items in the shipment
Product Tags	Any tags passed in the API request body
Hazmat (Hazardous Materials)	- If hazmat was indicated in the API request body, the value is True. - If hazmat was not indicated in the API request body, the value is False.

Rate selection results

The Rate Selection Results section includes the carrier and service method selected for the shipment, the shipment effective date, shipment weights, a delivery zone identifier, a Shipium-modeled total calculated cost, and a breakdown of cost elements.

Term	Description
Carrier Selected	The carrier selected to transport the package
Method Selected	The service method selected to transport the package
Shipment Effective Date	The first date that the request can be shipped. The date is determined by the value passed in the API request body, plus the configuration for your organization's account (e.g., weekends, holidays, carrier schedule).
Billable Weight	The weight used on the rate table to select an estimated cost. The physical weight is configured by the carrier and is typically rounded up. Dimensional weight will be displayed if used for rate selection.
Dim (Dimensional) Weight	Dim weight is the amount of space a package occupies in relation to its actual weight, as defined by the carrier. This value is typically Length (l) x Width (w) x Height (h) / dim weight divisor.
Physical Weight	The physical weight of the package included in the API request body
Zone ID	The Shipium delivery zone as defined by the carrier-identified zone
Calculated Cost	The Shipium modeled total cost of the shipment estimated by your organization's account configuration and carrier contract
Cost Elements	Breakdown of the calculated cost, to follow:
Base Rate (Base)	The rate table (weight to zone)
Surcharges	Any additional carrier costs associated with the shipment. Surcharges apply globally.
Surcharge Modifiers	Any discounts applied to the surcharges, as established in your organization's carrier contract. You also may have custom surcharge modifiers configured.

Service method

The Service Method section provides details about the carriers and service methods that were evaluated but not selected for a shipment. Information includes a Shipium-modeled cost of the shipment, the estimated delivery date, and the selection status for each carrier and service method. The selection status provides a reason why the carrier and service method were not selected.

Term	Description
Service Method	The carrier service method
Cost	The Shipium modeled cost of the shipment
Estimated Delivery (DDD)	The Shipium predicted date for a delivery at product checkout, based on time-in-transit values. The clock icon at the top of the column enables you to change time zones.
Selection Status	The status of the carrier service method evaluated for the requested shipment. The reason for each method that was not selected is provided. This value can be: - Selected - Label Created - Selected - Carrier Error - Failover - Label Created - Evaluated (met shipment criteria passed in the API request body but not the least expensive service method) - Filtered (did not meet shipment criteria passed in the API request body; reason provided)

Resources

Your Implementation team member is available to help you access your organization's shipment details. However, you might find these resources helpful: