Carrier and Method Selection Flow
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.
Shipment registration examples
These examples show the different POST body options for Carrier and Method Selection.
Option 1: Shipment request using packagingId
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
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 toshippedDateTime
, 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 apackagingTypeId
topackagingDetails
or a custompackagingDetails
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 () 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 incarrierSelectionExpiration
, 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 Supported Carriers.
More information on the API responses
As with all Shipium API responses, this API follows the API Response Codes standards unless otherwise specified.
Updated 3 months ago