Get started

To use the Carrier and Method Selection API, you must first set up your account to use Shipium's Carrier and Method Selection service. Information about carrier and method selection within the Shipium platform and setting up your organization's account to use the service can be found in the Carrier and Method Selection documentation.

The rest of this document provides instructions for using the API.

How the Carrier and Method Selection API fits into your workflow

The Carrier and Method Selection API runs carrier selection on a shipment that already exists in the Shipium platform. Unlike the Carrier and Method Selection & Shipment Label API, which handles shipment creation, carrier selection, and label generation in a single call, this API is designed for organizations that manage these steps separately.

📘

Recommended approach for most use cases

Shipium recommends the Carrier and Method Selection & Shipment Label API for most organizations, whether or not you need to generate a shipping label. The Carrier and Method Selection API is intended for multi-step workflows where your organization needs to decouple shipment creation and carrier selection into separate API calls.

Pre-requisite: Create a shipment

Before calling the Carrier and Method Selection API, you must create a shipment in the Shipium platform using the Create Shipment endpoint (POST /api/v1/deliveryexperience/shipment). The Create Shipment call is where you provide the shipment's origin and destination addresses, line items, package dimensions, weights, and other shipment details. Shipium stores this data and returns a shipiumShipmentId that you will use as a path parameter when calling the Carrier and Method Selection API.

Because the shipment data is already stored, the Carrier and Method Selection API request body contains only carrier selection parameters that influence how the selection is made, such as currency, packaging type overrides, and filtering controls. You do not need to provide addresses, line items, or other shipment details again.

Multi-step workflow

In a multi-step workflow, your organization separates the shipment process into distinct API calls.

1. Create Shipment. Register the shipment with the Shipium platform by providing addresses, line items, dimensions, and weights. The response includes a shipiumShipmentId.
2. Carrier and Method Selection (this API). Using the shipiumShipmentId from the previous step, ask Shipium to evaluate carriers and determine the optimal carrier and service method for the shipment.
3. Label Generation. Generate a shipping label based on the carrier decision.

This approach is useful when your organization needs to review the carrier decision before committing to a label, runs carrier selection at a different point in the warehouse workflow than label printing, or needs to re-run carrier selection on the same shipment if conditions change.

For guidance on creating shipments with partial data and completing them at a later time, see Partial (Multi-Step) Shipments.

Determine carrier and ship method with the Carrier and Method Selection API

The Shipium Carrier and Method Selection API assumes you're using one of the authentication mechanisms detailed in our authentication documentation. The endpoint for Carrier and Method Selection API calls is included in the table below.

Example cURL call

This example shows a request to run the carrier selection process on an existing shipment:

curl --request POST \
  --url https://api.shipium.com/api/v1/deliveryexperience/shipment/{shipiumShipmentId}/carrierSelection \
  --header 'accept: application/json' \
  --header $AUTHSTRING \
  --header 'content-type: application/json' \
  --data 'INSERT REQUEST BODY FROM BELOW'

Example request body

The following fields should be included in your JSON request.

{
  "currencyCode": "usd",
  "shippedDateTime": "2024-03-21T17:29:51.571Z",
  "packagingType": {
    "packagingMaterial": "box",
    "packagingSizeName": "13x12x10 box",
    "packagingTypeId": "ebd94f8b-d390-4c9c-987f-b88343f5bf45",
    "linearDimensions": {
      "linearUnit": "in",
      "length": 13,
      "width": 12,
      "height": 10
    },
    "packagingWeight": {
      "weightUnit": "lb",
      "weight": 50
    }
  },
  "carrierServiceMethodAllowList": [
    "fedex-ground",
    "ups-ground"
  ],
  "includeInjectionProfiles": true,
  "injectionParameters": [
    {
      "injectionProfileId": "0c3bdcfd-765b-4084-954e-76aa59dbd41d",
      "injectionSiteId": "3feb958c-414e-49f4-b15b-68f8f1cd02df"
    }
  ],
  "ignoreCarrierMinimumDimensions": false,
  "serviceMethodPoBoxAllowList": [
    "usps-priority-mail"
  ],
  "testMode": true
}

Example response body

{
  "carrierSelectionId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "shipiumShipmentId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "partnerShipmentId": "YOUR-SHIPMENT-ID-001",
  "shipiumTenantId": "9a8b7c6d-5e4f-3210-fedc-ba0987654321",
  "partnerTenantId": "your-partner-tenant-id",
  "carrierDecision": {
    "status": "success",
    "statusDetails": "Carrier selection completed successfully",
    "partnerId": "9a8b7c6d-5e4f-3210-fedc-ba0987654321",
    "carrierAccountId": "fedex-account-001",
    "serviceMethodIdentifier": "urn:carrierrate:86c6230a-4a2b-4f9b-8b71-a51627bbbcb2:1",
    "carrier": "fedex",
    "carrierServiceName": "FedEx Ground",
    "serviceMethodName": "FedEx Ground",
    "carrierServiceMethodId": "fedex-ground",
    "thirdPartyBilling": false,
    "carrierEstimatedPriceDetails": {
      "currencyCode": "usd",
      "shippingCost": 8.75,
      "insuranceCost": 0,
      "accessorials": 1.25,
      "duty": 0,
      "taxes": 0,
      "totalCost": 10.00,
      "adjustedLabelCost": 10.00,
      "carrierCompareCost": 9.50,
      "carrierInvoiceCost": 10.00,
      "operationalCost": 10.00
    },
    "ruleSetProcessingResultSummary": {
      "result": "selection_made",
      "selectedCarrierServiceMethodIdentifiers": [
        "fedex-ground"
      ],
      "ruleMakingSelection": {
        "ruleId": "rule-001",
        "ruleUrn": "urn:rule:rule-001",

Request and response fields for API calls

The following tables provide required, conditional, and optional fields for calling the Carrier and Method Selection API. You can find additional support in the Carrier and Method Selection API Reference.

Required fields

Conditional fields

Optional fields

Response attributes

The Carrier and Method Selection response attributes are defined in the following table.

Resources

Your Shipium team member is available to help along the way. However, you might find these resources helpful:

• Terms and Definitions

• Troubleshooting Guide

• Contact Shipium Support