Carrier and Method Selection Flow

Suggest Edits

Overview

Use the Shipium Carrier Selection API to determine the least expensive carrier and ship method that meets a set of rules you define for any given shipment. Once a given carrier and method have been determined, your software can obtain a label for that shipper as appropriate, or use our upcoming Carrier Shipment Label Flow as a single interface to all of the major shipping carriers.

Configuration and RuleSets

Before starting to use the API itself, your organization must set up one or more carriers and associated shipment methods.

For more details, see the documentation for the Shipium Console Application, specifically the section titled Shipium Carrier Selection.

Ultimately, these settings determine how a shipping carrier and method are selected for each shipment under the covers of the API. This section shows how to get a carrier and method from the API itself, assuming at least one carrier and method has been configured for your Partner account.

The shipment entity

In the Shipium APIs, a shipment represents a package, its contents, a source location (either an FC identifier or an address), a destination location, and any additional flags or shipment properties that sometimes impact the carrier decision.
You can either pre-register a shipment entity and then pass the identifier associated with the shipment for carrier selection, or pass the same contents as are required for creating a shipment into the selection API. The shipment structure is the same in either case.

Registering a shipment

You register a shipment by POSTing it to /v2/deliveryexperience/shipment with the fields shown in the following examples. There are two ways to call this API:

  • using a pre-configured packagingId (recommended)
  • by passing packageDetails in-line.

An example of each is shown below.

📘

Authentication for API calls

In the cURL examples on this page, the environment variable AUTHSTRING is used to handle authorization. The recipe below shows how to set it correctly for both OAuth and API Key users.

🔐
Authenticating for Curl
Open Recipe

Shipment registration examples

These examples show the different POST body options for Carrier and Method Selection.

Option 1: Shipment request using packagingId

This example shows the cURL request:

curl --request POST \
  --url <<api_url>>/api/v1/deliveryexperience/shipment \
  --header 'accept: application/json' \
  --header $AUTHSTRING \
  --header 'content-type: application/json' \
  --data '{"partnerShipmentId":"myCustomPartnerShipmentId123", "orderedDateTime":"2019-10-29T09:12:33.123456Z", "shippedDateTime": "2019-11-01T09:12:33.123456Z", "shipOption":"Standard", "shipmentTags":[ "custom_tag" ], "destinationAddress":{ "addressType":"commercial", "city":"Albuquerque", "company":"ACME", "countryCode":"US", "name":"WileE.Coyote", "postalCode":"87121", "state":"NM", "street1":"123 Warehouse St.", "street2":"Suite42" }, "orderItemQuantities":[ { "productDetails":["ormd","lio"], "productId":"RN03947--Z43121", "quantity":3 } ], "packagingType": {"packagingId":"cf3daf7d-6fca-46c2-9d9e-30a476dcc1e4"}, "totalWeight":{ "weight":50, "weightUnit":"lb" }, "shipFromAddress":{ "addressType":"commercial", "city":"Albuquerque", "company":"ACME", "countryCode":"US", "name":L. Merfudd", "postalCode":"87121", "state":"NM", "street1":"123 Main St.", "street2":"Suite42" }}'

This example shows the JSON equivalent:

{
  "partnerShipmentId": "myCustomPartnerShipmentId123",
  "orderedDateTime": "2019-10-29T09:12:33.123456Z",
  "shippedDateTime": "2019-11-01T09:12:33.123456Z",
  "shipOption": "Standard",
  "referenceIdentifier": "yourCustomIdentifier",
  "shipmentTags": [
    "custom_tag"
  ],
  "destinationAddress": {
    "addressType": "residential",
    "name": "Wile E. Coyote",
    "company": "ACME",
    "street1": "123 Warehouse St.",
    "street2": "Suite 42",
    "city": "Albuquerque",
    "state": "NM",
    "postalCode": "87121",
    "countryCode": "US"
  },
  "orderItemQuantities": [
    {
      "productDetails": ["ormd", "lio"],
      "productId": "RN03947--Z43121",
      "quantity": 3
    }
  ],
  "packagingType": {
    "packagingTypeId": "cf3daf7d-6fca-46c2-9d9e-30a476dcc1e4",
  },
  "totalWeight": {
      "weight": 50,
      "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"
  }
}

Option 2: Shipment request using packageDetails

Certain products may require a custom box or ship in their own container and this option covers those use cases. This is primarily for those cases where you use a non-standard packaging size, which we like to refer to as a "Frankenbox".

This example shows the JSON: 

{
  "partnerShipmentId": "myCustomPartnerShipmentId123",
  "orderedDateTime": "2019-10-29T09:12:33.123456Z",
  "shippedDateTime": "2019-11-01T09:12:33.123456Z",
  "shipOption": "Standard",
  "referenceIdentifier": "yourCustomIdentifier",
  "shipmentTags": [
    "custom_tag"
  ],
  "destinationAddress": {
    "addressType": "commercial",
    "city": "Albuquerque",
    "company": "ACME",
    "countryCode": "US",
    "name": "Wile E. Coyote",
    "postalCode": "87121",
    "state": "NM",
    "street1": "123 Warehouse St.",
    "street2": "Suite 42"
  },
  "orderItemQuantities": [
    {
      "deliveryEstimateId": "0b3d140a-525b-43a7-896c-cdc381580d61",
      "partnerOrderId": "myCustomPartnerOrderId123",
      "productDetails": ["ormd", "lio"],
      "productId": "RN03947--Z43121",
      "quantity": 3,
      "shipiumOrderId": "4dc43fff-c3af-4d7b-8a18-e01f2b4cb312"
    }
  ],
  "packagingType": {
    "linearDimensions": {
      "height": 10,
      "length": 13,
      "width": 12,
      "linearUnit": "in"
    },
    "packagingSizeName": "13x12x10 Box",
    "packagingWeight": {
      "weight": 12,
      "weightUnit": "oz "
    },
    "packagingMaterial": "box"
  },
  "totalWeight": {
      "weight": 50,
      "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"
  }
}

Option 3: Updating an existing shipment entity with a Shipment Ship Date

The general form for updating shipments is shown below:

<<api_url>>/api/v1/deliveryexperience/order/{shipiumOrderId|partnerOrderId}/shipment

In this form you must replace {shipiumShipmentId | partnerShipmentId} with either our shipment identifier or your own, if one was provided when the shipment was created.

This example shows a cURL request for updating shipments:

curl --request PATCH \
  --url <<api_url>>/api/v1/deliveryexperience/order/POID-12345/shipment \
  --header 'accept: application/json' \
  --header $AUTHSTRING \
  --header 'content-type: application/json' \
  --data '{"shippedDateTime": "2019-11-01T09:12:33.123456Z"}'

The example below shows the shippedDateTime passed in the body:

{
    "shippedDateTime": "2019-11-01T09:12:33.123456Z"
}

📘

Notes

  • In the above we use shipmentShipDate as the expected ship date of this shipment, as opposed to shippedDateTime, the date and time at which a shipment actually left the warehouse.
  • The above call depends on the shipment being populated with all of the required fields. An incomplete or invalid shipment returns error 422. Use PUT to populate the necessary fields before calling /carrierselect as needed.

Shipment response fields

A shipment response is the same shipment that was registered, including a shipiumShipmentId (the internally generated Shipium canonical identifier) and any other additional properties that were modified.

{
  "partnerShipmentId": "myCustomPartnerShipmentId123",
  "shipiumShipmentId": "49cf130d-b297-4c12-aa7d-82ea80208fde",
  "orderedDateTime": "2019-10-29T09:12:33.123456Z",
  "shippedDateTime": "2019-11-01T09:12:33.123456Z",
  "shipOption": "Standard",
  "referenceIdentifier": "yourCustomIdentifier",
  "shipmentTags": [
    "string"
  ],
  "destinationAddress": {
    "addressType": "commercial",
    "city": "Albuquerque",
    "company": "ACME",
    "countryCode": "us",
    "name": "Wile E. Coyote",
    "postalCode": "87121",
    "state": "NM",
    "street1": "123 Warehouse St.",
    "street2": "Suite 42"
  },
  "orderItemQuantities": [
    {
      "deliveryEstimateId": "0b3d140a-525b-43a7-896c-cdc381580d61",
      "partnerOrderId": "myCustomPartnerOrderId123",
      "productDetails": ["ormd", "lio"],
      "productId": "RN03947--Z43121",
      "quantity": 3,
      "shipiumOrderId": "4dc43fff-c3af-4d7b-8a18-e01f2b4cb312"
    }
  ],
  "packagingType": {
    "linearDimensions": {
      "height": 10,
      "length": 13,
      "linearUnit": "in",
      "width": 12
    },
    "packagingSizeName": "13x12x10 Box",
    "packagingWeight": {
      "weight": 12,
      "weightUnit": "oz "
    },
    "packagingMaterial": "box",
    "packagingTypeId": "cf3daf7d-6fca-46c2-9d9e-30a476dcc1e4",
  },
  "totalWeight": {
      "weight": 50,
      "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"
  }
}

📘

Note

The packagingDetails item is always expanded in the response, whether you pass a packagingTypeId to packagingDetails or a custom packagingDetails object in the request.

Requesting Carrier Selection for an existing shipment

The general form of the Carrier Selection Endpoint is shown below:

<<api_url>>/api/v1/deliveryexperience/shipment/{shipiumShipmentId | partnerShipmentId}/carrierSelection

In the above you would replace {shipiumShipmentId | partnerShipmentId} with either our shipment identifier or your own (if this was provided when the shipment was created).

This example shows a Carrier Selection endpoint cURL request:

curl --request POST \
  --url <<api_url>>/api/v1/deliveryexperience/shipment/49cf130d-b297-4c12-aa7d-82ea80208fde/carrierSelection \
  --header 'accept: application/json' \
  --header $AUTHSTRING \
  --header 'content-type: application/json' \
  --data '{"currencyCode": "usd"}'

The only additional data needed is a currencyCode used to return information in the appropriate currency.

Note: PATCH contents for shipmentShipDate can be used here instead, as part of the POST for carrierSelection, if that makes sense for your call flow.

The response to the request contains both a link to the details of the original shipment (:grey-question:) and the details of the ship method and carrier that have been selected:

{
  "carrierDecision": {
    "carrier": "UPS",
    "carrierAccountId": "4e14aaa3-198b-4861-b658-faf51031c84c",
    "carrierEstimatedPriceDetails": {
      "currencyCode": "usd",
      "accessorials": 0.0,
      "duty": 0.0,
      "insuranceCost": 0.0,
      "shippingCost": 8.74,
      "taxes": 0.0,
      "totalCost": 5.85
    },
    "serviceMethodName": "Ground",
    "partnerId": "c645ea83-d161-4e28-b8cb-39bf1a620cd3",
    "serviceMethodUrn": "c645ea83-d161-4e28-b8cb-39bf1a620cd3:4e14aaa3-198b-4861-b658-faf51031c84c:83fe5227-a765-45b2-bc2a-cb919ddce922:1"
  },
  "carrierSelectionDateTime": "2020-10-12T22:42:02.152Z",
  "carrierSelectionExpiration": "2020-10-12T22:42:02.152Z",
  "carrierSelectionId": "9d150e3a-125d-4557-92ef-3dcc28a62af9",
  "ruleSetName": "Standard RuleSet",
  "ruleSetUrn": "c645ea83-d161-4e28-b8cb-39bf1a620cd3:de1063a7-4d56-4257-b404-71e0f6e7c9d6:1",
  "partnerShipmentId": "PSID-1234",
  "shipiumShipmentId": "57A72936-B82D-4361-99C6-91DC52513756"
}

📘

Notes

  • shippingCost above is set up as a "currencyAmount" structure type with a set of amounts and an ISO 4217 currency code specified along with the amounts.
  • A carrierSelection is usable until the date specified in carrierSelectionExpiration, after which it must be updated. Currently that duration is two hours.

📘

See also

For a list of CarrierID and Carrier Service Method Id values, see List of canonical carrierId and carrierServiceMethodId values.

📘

More information on the API responses

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

Updated 11 months ago