# 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](https://docs.shipium.com/docs/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](https://docs.shipium.com/docs/carrier-and-method-selection-and-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](https://docs.shipium.com/docs/carrier-and-method-selection-and-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](https://docs.shipium.com/reference/shipmentcreatev1) 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](https://docs.shipium.com/reference/shipmentcreatev1).** 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](https://docs.shipium.com/docs/shipment-label-api).** 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](https://docs.shipium.com/docs/partial-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](https://docs.shipium.com/docs/authentication). The endpoint for Carrier and Method Selection API calls is included in the table below.

| API type | API endpoint |
| --- | --- |
| POST | `https://api.shipium.com/api/v1/deliveryexperience/shipment/{shipiumShipmentId}/carrierSelection` |

## Example cURL call

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

```curl
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.

```json
{
  "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

```json
{
  "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"
      ]
    }
  }
}

# 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](https://docs.shipium.com/reference/createcarrierselectionv1).

## Required fields

| Field | Details |
| --- | --- |
| `currencyCode` | **Type:** String<br>**Example:**`usd`<br>**Description:** Currency in which all the rates for shipping carrier selection costs will be calculated |

## Conditional fields

| Field | Details |
| --- | --- |
| `packagingType.linearDimensions.linearUnit` | **Type:** String (enumeration)<br>**Values:**`cm` (centimeter), `in` (inch)<br>**Condition:** Required if `packagingTypeId` is not included<br>**Description:** The unit in which linear dimensions are provided |
| `packagingType.linearDimensions.length` | **Type:** Number (float)<br>**Example:**`13`<br>**Condition:** Required if `packagingTypeId` is not included<br>**Description:** The longest linear dimension (i.e., the longest side of a box or envelope) |
| `packagingType.linearDimensions.width` | **Type:** Number (float)<br>**Example:**`12`<br>**Condition:** Required if `packagingTypeId` is not included<br>**Description:** The second longest linear dimension (i.e., the second longest side of a box or envelope) |
| `packagingType.linearDimensions.height` | **Type:** Number (float)<br>**Example:**`10`<br>**Condition:** Required if `packagingTypeId` is not included<br>**Description:** The shortest linear dimension.<br>**Note on envelopes:** This height should represent the highest product you would reasonably put in this envelope before losing more than 10% of the length of the envelope in other dimensions. |
| `injectionParameters.injectionSiteId` | **Type:** String<br>**Condition:** Must be paired with `injectionProfileId`<br>**Description:** The Shipium ID or the partner-provided ID of an [injection](https://docs.shipium.com/docs/injection) site that should be considered during carrier selection. If an injection site ID is specified, it must be accompanied by an injection profile ID. |

## Optional fields

| Field | Details |
| --- | --- |
| `shippedDateTime` | **Type:** String (date-time)<br>**Example:**`2025-09-17T20:10:17.123456Z`<br>**Description:** The timestamp for when a partner shipped the product from their warehouse; the timestamp must be a valid [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) timestamp. |
| `packagingType.packagingMaterial` | **Type:** String (enumeration)<br>**Values:**`box`, `envelope`, `flat_pack`, `mailing_tube`, `parcel_pallet`<br>**Description:** The type of [packaging](https://docs.shipium.com/docs/configure-packaging-configuration) used to create the package for the shipment |
| `packagingType.packagingSizeName` | **Type:** String<br>**Example:**`13x12x10 box`<br>**Description:** A custom name for the [packaging](https://docs.shipium.com/docs/configure-packaging-configuration) |
| `packagingType.packagingTypeId` | **Type:** String<br>**Example:**`ebd94f8b-d390-4c9c-987f-b88343f5bf45`<br>**Description:** The `packagingTypeId` that was used for this [package](https://docs.shipium.com/docs/configure-packaging-configuration). When this value is present, the dimensions defined in the partner are used. When this value is absent, `linearDimensions` is required. |
| `packagingType.packagingWeight.weightUnit` | **Type:** String (enumeration)<br>**Values:**`g` (gram), `kg` (kilogram), `lb` (pound), `oz` (ounce)<br>**Description:** The unit in which weight values are provided |
| `packagingType.packagingWeight.weight` | **Type:** Number (float)<br>**Example:**`50`<br>**Description:** The value of the weight |
| `includeInjectionProfiles` | **Type:** Boolean<br>**Values:**`true` or `false`<br>**Description:** If `true`, service methods from the configured [injection](https://docs.shipium.com/docs/injection) profiles will be considered during carrier selection. |
| `injectionParameters.injectionProfileId` | **Type:** String<br>**Description:** The Shipium ID or the partner-provided ID of an [injection](https://docs.shipium.com/docs/injection) profile that should be considered during carrier selection |
| `testMode` | **Type:** Boolean<br>**Values:**`true` or `false`<br>**Description:** If `true`, no actual labels are created, only a representation of the [label](https://docs.shipium.com/docs/understanding-carrier-selection-label-test-mode). No money is charged to the underlying account. |
| `ignoreRuleSets` | **Type:** Boolean<br>**Values:**`true` or `false`<br>**Description:** When `true`, any configured [rule sets](https://docs.shipium.com/docs/carrier-selection-rules) will be ignored during carrier selection. |
| `customsInfo.taxIdentificationNumber` | **Type:** String<br>**Example:**`12345`<br>**Description**: This optional value can be passed to override any [tax ID number](https://docs.shipium.com/docs/tax-identification-number) (also known as an employer identification number, or EIN) that is configured in your network settings. |
| `carrierServiceMethodAllowList` | **Type:** Array of strings<br>**Description:** A list of `carrierServiceMethodId` values and/or carrier names that should be considered for selection. When provided, only the specified carriers and service methods will be evaluated. If an empty list is passed, it is treated as if no list was specified. You can find a list of `carrierServiceMethodId` values in [Supported Carriers](https://docs.shipium.com/docs/supported-carriers). |
| `serviceMethodPoBoxAllowList` | **Type:** Array of strings<br>**Description:** A list of `serviceMethodId` values that will be considered for USPS PO box delivery that otherwise would be filtered out as they do not support USPS PO box delivery for the shipment. You can find a list of `serviceMethodId` values in [Supported Carriers](https://docs.shipium.com/docs/supported-carriers). |
| `ignoreCarrierMinimumDimensions` | **Type:** Boolean<br>**Values:**`true` or `false`<br>**Description:** When `true`, the minimum dimensions of carriers will effectively be ignored when deciding if a carrier service method is eligible to be considered during costing. The default value is `false`. |

## Response attributes

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

| Response attribute | Description |
| --- | --- |
| `carrierSelectionId` | Unique ID of the carrier selection for later reference |
| `shipiumShipmentId` | The unique identifier for the shipment |
| `partnerShipmentId` | The optional unique identifier that may be used for the shipment |
| `shipiumTenantId` | The Shipium-generated tenant ID; when present, this is used to indicate the tenant associated with the shipment. |
| `partnerTenantId` | The tenant ID provided by your organization; when present, this is used to indicate the tenant associated with the shipment. |
| `carrierDecision.status` | Defines the result of the carrier selection call; values returned will be `success`, `no_decision`, or `uncosted`. |
| `carrierDecision.statusDetails` | Details explaining the result status; pertinent when the status is `no_decision` |
| `carrierDecision.partnerId` | Your organization's unique ID |
| `carrierDecision.carrierAccountId` | Unique ID of the carrier account selected for shipping |
| `carrierDecision.serviceMethodIdentifier` | Identifier of the specific version of the service method of the shipping carrier selected |
| `carrierDecision.carrier` | The carrier that was used for delivering the package to your customer |
| `carrierDecision.carrierServiceName` | The name of the carrier service method selected |
| `carrierDecision.thirdPartyBilling` | Indicates if the selected service method will be [billed to a third party](https://docs.shipium.com/docs/bill-a-third-party) |
| `carrierDecision.carrierEstimatedPriceDetails                     .currencyCode` | Currency in which all price line items are stored |
| `carrierDecision.carrierEstimatedPriceDetails                     .shippingCost` | The cost of the shipment charged by the carrier |
| `carrierDecision.carrierEstimatedPriceDetails                     .insuranceCost` | The cost of the insurance added to the shipment |
| `carrierDecision.carrierEstimatedPriceDetails                     .accessorials` | Costs added to the shipment outside the normal basics of dock-to-dock transportation such as special equipment required, lift gates, or non-commercial destinations |
| `carrierDecision.carrierEstimatedPriceDetails                     .duty` | Cost of duties added to the shipment |
| `carrierDecision.carrierEstimatedPriceDetails                     .taxes` | Cost of taxes added to the shipment |
| `carrierDecision.carrierEstimatedPriceDetails                     .totalCost` | The total cost of the shipment |
| `carrierDecision.carrierEstimatedPriceDetails                     .adjustedLabelCost` | Cost used for carrier selection adjusted based on limit minimums |
| `carrierDecision.carrierEstimatedPriceDetails                     .carrierCompareCost` | Cost expected to be provided in the carrier response, not including custom adjustments or hidden surcharges |
| `carrierDecision.carrierEstimatedPriceDetails                     .carrierInvoiceCost` | Expected cost that the carrier will charge |
| `carrierDecision.carrierEstimatedPriceDetails                     .operationalCost` | Carrier invoice cost plus operational costs such as injection line haul |
| `carrierDecision.serviceMethodName` | Name of the carrier service method selected during the carrier selection process |
| `carrierDecision.carrierServiceMethodId` | Maps to the unique internal Shipium ID that represents a carrier service method definition; see [Supported Carriers](https://docs.shipium.com/docs/supported-carriers) for a list of carrier service method IDs. |
| `carrierDecision.ruleSetProcessingResultSummary                    .result` | Description of the result of the rule set processing; values returned will be `selection_made` or `no_selection`. |
| `carrierDecision.ruleSetProcessingResultSummary                     .selectedCarrierServiceMethodIdentifiers` | Ordered list of service methods selected by the rule set processing if a selection was made |
| `carrierDecision.ruleSetProcessingResultSummary                     .ruleMakingSelection.ruleId` | The unique ID of the rule processed |
| `carrierDecision.ruleSetProcessingResultSummary                     .ruleMakingSelection.ruleUrn` | The URN of the rule processed |
| `carrierDecision.ruleSetProcessingResultSummary                     .ruleMakingSelection.name` | The name of the rule processed |
| `carrierDecision.ruleSetProcessingResultSummary                     .ruleSetUrn` | Versioned identifier of the rule set processed |
| `carrierDecision.ruleSetProcessingResultSummary                     .processingTimestamp` | The timestamp at which the rule set was processed |
| `carrierDecision.effectiveShipDateTime` | The earliest that a shipment can leave the fulfillment center, or origin, based on the shipped date time and the schedules for that origin and the carriers |
| `carrierDecision.estimatedDeliveryDate` | The date and time by when the package is estimated to be delivered to the customer |
| `carrierDecision.estimatedInjectionDateTime` | The estimated date that the shipment will arrive at the injection site |
| `carrierDecision.effectiveDesiredDeliveryDate` | The adjusted desired delivery date that Shipium used for carrier selection. This date includes all adjustments Shipium has made to the requested desired delivery date, such as business rules and holidays. |
| `carrierDecision.currencyCode` | The currency in which all shipping carrier selection costs were calculated |
| `carrierDecision.injectionDetails                     .requestInjectionProfileId` | You can provide either `partnerInjectionProfileId` or `shipiumInjectionProfileId` in the request, and this attribute records the injection profile identifier you provided in the request. |
| `carrierDecision.injectionDetails                     .partnerInjectionProfileId` | Unique to the asset ID that you provided to the injection profile. |
| `carrierDecision.injectionDetails                     .shipiumInjectionProfileId` | Injection profile identifier |
| `carrierDecision.injectionDetails                     .requestInjectionSiteId` | You can provide either `partnerInjectionSiteId` or `shipiumInjectionSiteId` in the request, and this attribute records the injection site identifier you provided in the request. |
| `carrierDecision.injectionDetails                     .partnerInjectionSiteId` | Unique to the partner asset ID that you provided to the injection site |
| `carrierDecision.injectionDetails                     .shipiumInjectionSiteId` | Injection site identifier |
| `carrierDecision.injectionDetails                     .injectionCostDetails.injectionLineItemRate` | The amount of the rate modification |
| `carrierDecision.injectionDetails                     .injectionCostDetails                     .injectionLineItemCurrencyCode` | The currency of the rate |
| `carrierDecision.injectionDetails                     .injectionCostDetails.injectionRateModifier                     .modifierType` | The type of the injection rate modifier |
| `carrierDecision.injectionDetails                     .injectionCostDetails.injectionRateModifier                     .modifierValue` | The value of the modification |
| `carrierSelectionDateTime` | The ISO-8601 formatted date when the carrier selection decision was made |
| `carrierSelectionExpiration` | The ISO-8601 formatted date defining the point in time when the carrier selection details expire and cannot be acted upon |
| `currencyCode` | The currency in which all shipping carrier selection costs were calculated |

# Resources

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

- [Terms and Definitions](https://docs.shipium.com/docs/common-terms)
- [Troubleshooting Guide](https://docs.shipium.com/docs/troubleshooting-guide)
- [Contact Shipium Support](https://docs.shipium.com/docs/contacting-shipium-support)