For AI agents: visit https://docs.shipium.com/llms.txt for an index of all pages formatted in Markdown and endpoints in OpenAPI.
# Get started [Skip link to Get started](https://docs.shipium.com/docs/ltl-shipment-cost-compare-api\#get-started)
To use the LTL Shipment Cost Compare API, you must first configure your account. Guidance can be found in the [LTL (Less Than Truckload) Shipments](https://docs.shipium.com/docs/ltl-less-than-truckload-shipments) documentation. This document provides instructions for using the API.
The LTL Shipment Cost Compare API assumes you're using one of the authentication mechanisms detailed in our [authentication documentation](https://docs.shipium.com/docs/authentication).
> 🔐
>
> ### Authentication for API Calls [Skip link to Authentication for API Calls](https://docs.shipium.com/docs/ltl-shipment-cost-compare-api\#authentication-for-api-calls)
>
> In the cURL example on this page, the environment variable `AUTHSTRING` is used to handle authorization. The recipe below shows how to set it correctly for both API Key and OAuth users.
🔐
Authenticating for Curl
Open Recipe
> 👍
>
> ### Test mode [Skip link to Test mode](https://docs.shipium.com/docs/ltl-shipment-cost-compare-api\#test-mode)
>
> Want to run some examples and not charge any real money against your account?
>
> You can add `testMode`: "true" to the data passed to any label call to retrieve labels without charging money in a carrier-specific manner. Most carriers will mark their labels in a way to make clear that they are void, such as inserting "VOID" throughout the label or using a predefined ID.
>
> The examples below contain the `testMode` flag to err on the side of caution – remove it to make production calls.
## When to use the LTL Shipment Cost Compare endpoint [Skip link to When to use the LTL Shipment Cost Compare endpoint](https://docs.shipium.com/docs/ltl-shipment-cost-compare-api\#when-to-use-the-ltl-shipment-cost-compare-endpoint)
Use the LTL Shipment Cost Compare API when you want to determine whether it's more economical to ship via LTL or parcel. This endpoint runs both LTL and parcel carrier selection in parallel and returns a recommendation based on cost.
This is the right endpoint when:
- **You want a side-by-side LTL vs. parcel cost comparison.** The endpoint returns both LTL and parcel pricing, plus a `recommendedTransportationType` indicating the less expensive viable option.
- You want to programmatically route shipments to the cheaper mode. Your integration can read `recommendedTransportationType` and act accordingly.
- **You want to retroactively evaluate past shipments.** Use `existingShipmentIds` to compare what a previously shipped order would cost as LTL versus its current parcel rate. Live re-rating ensures your comparison reflects current market rates.
If you've already decided to ship LTL and only need LTL pricing, you'll want to use the [LTL Shipment Cost API](https://docs.shipium.com/docs/ltl-shipment-cost-api) instead.
# Compare LTL and small package shipping costs [Skip link to Compare LTL and small package shipping costs](https://docs.shipium.com/docs/ltl-shipment-cost-compare-api\#compare-ltl-and-small-package-shipping-costs)
The endpoint for comparing the estimated cost between LTL and small package shipping is included in the following table.
| API type | API endpoint |
| --- | --- |
| POST | `https://api.shipium.com/api/v1/ltl/shipment/costCompare` |
## Choose an input method [Skip link to Choose an input method](https://docs.shipium.com/docs/ltl-shipment-cost-compare-api\#choose-an-input-method)
The API supports three mutually exclusive (but combinable) methods for providing shipment data. At least one must be populated:
- **shipments (inline).** Use when you want to provide full package details in a single API call without pre-creating shipments. This is the most common path for customers evaluating LTL vs. parcel at the point of shipment creation.
- **packedShipments.** Use when the load is already palletized or configured. Items in `packedShipments` are used for LTL costing only and are excluded from parcel comparison.
- **existingShipmentIds.** Use when you've already created Shipium shipments and want to retroactively compare LTL versus parcel pricing.
You can combine input methods in a single request. Items from `existingShipmentIds` and shipments are included in both the LTL load and the parcel comparison; items from `packedShipments` contribute only to the LTL load.
## Request and response fields for API calls [Skip link to Request and response fields for API calls](https://docs.shipium.com/docs/ltl-shipment-cost-compare-api\#request-and-response-fields-for-api-calls)
The following tables provide required, conditional, and optional fields for calling the LTL Shipment Cost Compare API. Fields are organized by their parent objects to reflect the request structure. You can find additional support in the [LTL Shipment Cost Compare API Reference](https://docs.shipium.com/reference/createltlcostcomparev1).
### Top-level request fields [Skip link to Top-level request fields](https://docs.shipium.com/docs/ltl-shipment-cost-compare-api\#top-level-request-fields)
#### Required fields [Skip link to Required fields](https://docs.shipium.com/docs/ltl-shipment-cost-compare-api\#required-fields)
| Field | Details |
| --- | --- |
| `currencyCode` | **Type:** String
**Example:**`usd`
**Description:** The 3-character [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code in which all the rates for shipping will be calculated and returned |
#### Conditional fields [Skip link to Conditional fields](https://docs.shipium.com/docs/ltl-shipment-cost-compare-api\#conditional-fields)
| Field | Details |
| --- | --- |
| `shipments` | **Type:** Array of `shipments` objects
**Condition:** Required if no value is provided for either `existingShipmentIds` or `packedShipments`
**Description:** The shipments that should be included in this LTL shipment; this can be used in conjunction with `existingShipmentIds` and/or `packedShipments`. At least one of `existingShipmentIds`, `shipments`, and `packedShipments` must not be empty or null. |
| `packedShipments` | **Type:** Array of `packedShipments` objects
**Condition:** Required if no value is provided for either `existingShipmentIds` or `shipments`
**Description:** The already packed LTL shipments that should be included in this LTL shipment; items in this list will only be used for LTL costing and will not have their packaging modified, nor be eligible for package carrier selection. Items in this list do not require corresponding Shipium shipments, nor will they create shipments. This can be used in conjunction with `existingShipmentIds` and/or `shipments`. At least one of `existingShipmentIds`, `shipments`, and `packedShipments` must not be empty or null. |
| `existingShipmentIds` | **Type:** Array of strings
**Condition:** Required if no value is provided for either `shipments` or `packedShipments`
**Description:** The Shipium or partner shipment IDs that should be included in this LTL shipment; these must be IDs for shipments created using the /api/v1/deliveryexperience/shipment endpoint, or an equivalent endpoint. These cannot be LTL shipments, must have `nmfcFreightClass` configured, and must have the same ship from and destination addresses as this LTL shipment. This can be used in conjunction with shipments and/or packedShipments. At least one of `existingShipmentIds`, `shipments`, and `packedShipments` must not be empty or null. |
#### Optional fields [Skip link to Optional fields](https://docs.shipium.com/docs/ltl-shipment-cost-compare-api\#optional-fields)
| Field | Details |
| --- | --- |
| `businessDaysOfTransit` | **Type:** Integer (int32)
**Example:**`3`
**Description:** Indicates the number of [business days](https://docs.shipium.com/docs/business-days-of-transit) from the ship time by when the shipment needs to be delivered |
| `desiredDeliveryDate` | **Type:** String
**Example:**`2019-10-31T20:00:00Z`
**Description:** The string representation of either an [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) date or a local date for [desired delivery](https://docs.shipium.com/docs/desired-and-exact-delivery-dates): `yyyy-mm-dd`. The date or date-time the package is intended to arrive to the customer. This is used to determine the most appropriate service method when generating a label. |
| `includeEvaluatedServiceMethodsInResponse` | **Type:** Boolean
**Values:**`true` or `false`
**Description:** When `true`, a request will expand information on the response to [include unselected service methods](https://docs.shipium.com/docs/evaluated-service-methods) that made it through filtering. |
| `includeLineItemsInEvaluatedServiceMethods` | **Type:** Boolean
**Values:**`true` or `false`
**Description:** When `true`, a response will [include line item information](https://docs.shipium.com/docs/evaluated-service-methods) for the returned evaluated service methods, provided that `includeEvaluatedServiceMethodsInResponse` is also set to true. |
| `partnerLtlCostId` | **Type:** String
**Example:**`myCustomPartnerLTLShipmentId123`
**Description:** An optional unique identifier that may be used for this LTL cost |
| `shippedDateTime` | **Type:** String (date-time)
**Example:**`2019-10-29T09:12:33.123456Z`
**Description:** The [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) timestamp for when you (or your fulfillment partner) shipped the product from your (or their) warehouse; if not provided, this value defaults to `orderedDateTime`. |
| `tenantId` | **Type:** String
**Description:** Either the Shipium `tenantId` or your organization's unique `tenantId` for the [tenant](https://docs.shipium.com/docs/configure-fulfillment-configuration#about-tenants-in-the-shipium-platform) that the shipment is for; if this is not supplied, the shipment will be associated with your organization, and only your network-wide [fulfillment contexts](https://docs.shipium.com/docs/fulfillment-contexts) will be considered. |
| `testMode` | **Type:** Boolean
**Values:**`true` or `false`
**Description:** If `true`, a test mode LTL shipment will be created. LTL costing and carrier selection will consider carriers and service methods in [test mode](https://docs.shipium.com/docs/understanding-carrier-selection-label-test-mode), and label generation will generate a test label. |
### desiredDeliveryDateOptions fields [Skip link to desiredDeliveryDateOptions fields](https://docs.shipium.com/docs/ltl-shipment-cost-compare-api\#desireddeliverydateoptions-fields)
All fields in this object are optional. You can find more information about desired delivery date options in [Desired, Exact, & Guaranteed Delivery Dates](https://docs.shipium.com/docs/desired-and-exact-delivery-dates).
| Field | Details |
| --- | --- |
| `desiredDeliveryDateOptions.exactDateDelivery` | **Type:** Boolean
**Values:**`true` or `false`
**Description:** If `true`, this instructs the carrier to deliver the package on the date provided in the `desiredDeliveryDate` field. |
| `desiredDeliveryDateOptions.guaranteedDateDelivery` | **Type:** Boolean
**Values:**`true` or `false`
**Description:** If `true`, this indicates that your organization is willing to accept any applicable carrier date certain surcharge to the estimated label cost. Not all carriers support [guaranteed date delivery](https://docs.shipium.com/docs/desired-and-exact-delivery-dates#about-guaranteed-delivery-dates). This restricts carrier selection to service methods that can support guaranteed date delivery. |
| `desiredDeliveryDateOptions.upgradeCostDeltaMax` | **Type:** String
**Description:** If set, this is the maximum amount of additional spend that your organization is willing to pay to upgrade a shipment to the [desired delivery date](https://docs.shipium.com/docs/desired-and-exact-delivery-dates) (DDD) if the lowest cost carrier service method is unable to safely meet the DDD. |
| `desiredDeliveryDateOptions.currencyCode` | **Type:** String
**Description:** The [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code of the `upgradeCostDeltaMax` |
### destinationAddress fields [Skip link to destinationAddress fields](https://docs.shipium.com/docs/ltl-shipment-cost-compare-api\#destinationaddress-fields)
#### Required fields [Skip link to Required fields](https://docs.shipium.com/docs/ltl-shipment-cost-compare-api\#required-fields-1)
| Field | Details |
| --- | --- |
| `destinationAddress.countryCode` | **Type:** String
**Description:** The ISO 3166-1 [country code](https://docs.shipium.com/docs/non-us-address-formats) for the destination address |
| `destinationAddress.postalCode` | **Type:** String
**Description:** A country-code-appropriate postal code for the destination address |
| `destinationAddress.addressType` | **Type:** String (enumeration)
**Values:**`commercial`, `residential`
**Description:** The type of location for the destination address |
#### Conditional fields [Skip link to Conditional fields](https://docs.shipium.com/docs/ltl-shipment-cost-compare-api\#conditional-fields-1)
| Field | Details |
| --- | --- |
| `destinationAddress.phoneNumber` | **Type:** String
**Condition:** May be required for certain carriers and methods
**Description:** The phone number of the contact for the destination address |
| `destinationAddress.phoneNumberCountryCode` | **Type:** String
**Condition:** May be required for certain carriers and methods
**Description:** The phone number country code of the contact for the destination address |
#### Optional fields [Skip link to Optional fields](https://docs.shipium.com/docs/ltl-shipment-cost-compare-api\#optional-fields-1)
| Field | Details |
| --- | --- |
| `destinationAddress.name` | **Type:** String
**Description:** The name of the contact for the destination address |
| `destinationAddress.emailAddress` | **Type:** String
**Description:** The email address of the contact for the destination address |
| `destinationAddress.company` | **Type:** String
**Description:** The company name for the destination address |
| `destinationAddress.street1` | **Type:** String
**Description:** The first destination address line |
| `destinationAddress.street2` | **Type:** String
**Description:** The second destination address line |
| `destinationAddress.city` | **Type:** String
**Description:** The name of the city for the destination address |
| `destinationAddress.state` | **Type:** String
**Description:** The 2-letter postal abbreviation of the state for the destination address |
### shipFromAddress fields [Skip link to shipFromAddress fields](https://docs.shipium.com/docs/ltl-shipment-cost-compare-api\#shipfromaddress-fields)
#### Required fields [Skip link to Required fields](https://docs.shipium.com/docs/ltl-shipment-cost-compare-api\#required-fields-2)
| Field | Details |
| --- | --- |
| `shipFromAddress.countryCode` | **Type:** String
**Description:** The ISO 3166-1 [country code](https://docs.shipium.com/docs/non-us-address-formats) for the address of the location from which the package is being shipped |
| `shipFromAddress.postalCode` | **Type:** String
**Description:** A country-code-appropriate postal code for the address of the location from which the package is being shipped |
#### Optional fields [Skip link to Optional fields](https://docs.shipium.com/docs/ltl-shipment-cost-compare-api\#optional-fields-2)
| Field | Details |
| --- | --- |
| `shipFromAddress.name` | **Type:** String
**Description:** The name associated with the address from which the package is being shipped |
| `shipFromAddress.phoneNumber` | **Type:** String
**Description:** The phone number of the contact associated with the address from which the package is being shipped |
| `shipFromAddress.phoneNumberCountryCode` | **Type:** String
**Description:** The phone number country code of the contact associated with the address from which the package is being shipped |
| `shipFromAddress.emailAddress` | **Type:** String
**Description:** The email address of the contact associated with the address from which the package is being shipped |
| `shipFromAddress.company` | **Type:** String
**Description:** The company name associated with the address from which the package is being shipped |
| `shipFromAddress.street1` | **Type:** String
**Description:** The first address line of the location from which the package is being shipped |
| `shipFromAddress.street2` | **Type:** String
**Description:** The second address line of the location from which the package is being shipped |
| `shipFromAddress.city` | **Type:** String
**Description:** The city of the location from which the package is being shipped |
| `shipFromAddress.state` | **Type:** String
**Description:** The 2-letter postal abbreviation of the state of the location from which the package is being shipped |
| `shipFromAddress.addressType` | **Type:** String (enumeration)
**Values:**`commercial`, `residential`
**Description:** The type of location for the address of the location from which the package is being shipped |
### returnToAddress fields [Skip link to returnToAddress fields](https://docs.shipium.com/docs/ltl-shipment-cost-compare-api\#returntoaddress-fields)
#### Conditional fields [Skip link to Conditional fields](https://docs.shipium.com/docs/ltl-shipment-cost-compare-api\#conditional-fields-2)
| Field | Details |
| --- | --- |
| `returnToAddress.countryCode` | **Type:** String
**Condition:** Required if including `returnToAddress`
**Description:** The ISO 3166-1 [country code](https://docs.shipium.com/docs/non-us-address-formats) for the address of the location where the package is being returned |
| `returnToAddress.postalCode` | **Type:** String
**Condition:** Required if including `returnToAddress`
**Description:** A country-code-appropriate postal code for the address of the location where the package is being returned |
#### Optional fields [Skip link to Optional fields](https://docs.shipium.com/docs/ltl-shipment-cost-compare-api\#optional-fields-3)
| Field | Details |
| --- | --- |
| `returnToAddress.name` | **Type:** String
**Description:** The name associated with the address of the location where the package is being returned |
| `returnToAddress.phoneNumber` | **Type:** String
**Description:** The phone number of the contact associated with the address of the location where the package is being returned |
| `returnToAddress.phoneNumberCountryCode` | **Type:** String
**Description:** The phone number country code of the contact associated with the address of the location where the package is being returned |
| `returnToAddress.emailAddress` | **Type:** String
**Description:** The email address of the contact associated with the address of the location where the package is being returned |
| `returnToAddress.company` | **Type:** String
**Description:** The company name associated with the address of the location where the package is being returned |
| `returnToAddress.street1` | **Type:** String
**Description:** The first address line of the location where the package is being returned |
| `returnToAddress.street2` | **Type:** String
**Description:** The second address line of the location where the package is being returned |
| `returnToAddress.city` | **Type:** String
**Description:** The city of the location where the package is being returned |
| `returnToAddress.state` | **Type:** String
**Description:** The 2-letter postal abbreviation of the state of the location where the package is being returned |
| `returnToAddress.addressType` | **Type:** String (enumeration)
**Values:**`commercial`, `residential`
**Description:** The type of location for the address of the location where the package is being returned |
### units fields [Skip link to units fields](https://docs.shipium.com/docs/ltl-shipment-cost-compare-api\#units-fields)
All fields in this object are required.
| Field | Details |
| --- | --- |
| `units.currencyCode` | **Type:** String
**Example:**`usd`
**Description:** The [ISO-4217](https://www.iso.org/iso-4217-currency-codes.html) currency code in which monetary amounts for all currency units are represented in the response |
| `units.linearUnit` | **Type:** String (enumeration)
**Values:**`in` (inch), `cm` (centimeter)
**Description:** The unit in which all linear dimensions are represented in the response |
| `units.weightUnit` | **Type:** String (enumeration)
**Values:**`g` (gram), `kg` (kilogram), `oz` (ounce), `lb` (pound)
**Description:** The unit in which all weights are represented in the response |
### ltlShipmentParameters fields [Skip link to ltlShipmentParameters fields](https://docs.shipium.com/docs/ltl-shipment-cost-compare-api\#ltlshipmentparameters-fields)
#### Required fields [Skip link to Required fields](https://docs.shipium.com/docs/ltl-shipment-cost-compare-api\#required-fields-3)
| Field | Details |
| --- | --- |
| `ltlShipmentParameters.paymentDetails .payerType` | **Type:** String (enumeration)
**Values:**`consignee`, `shipper`, `thirdParty`
**Description:** The type of entity that is paying the carrier to deliver the shipment |
| `ltlShipmentParameters.paymentDetails .paymentTerms` | **Type:** String (enumeration)
**Values:**`collect`, `prePaid`, `thirdParty`
**Description:** The method being used to pay for the shipment |
| `ltlShipmentParameters.pickupDate` | **Type:** String
**Example:**`2024-12-31`
**Description:** The date when the LTL shipment will be picked up by the carrier |
#### Optional fields [Skip link to Optional fields](https://docs.shipium.com/docs/ltl-shipment-cost-compare-api\#optional-fields-4)
| Field | Details |
| --- | --- |
| `ltlShipmentParameters .carrierServiceMethodAllowList` | **Type:** Array of strings
**Description:** A list of `carrierServiceMethodIds`, Standard Carrier Alpha Code (SCAC) codes, and/or carriers that should be considered for LTL carrier selection; you can find more information in [Specify Carrier Service and Method](https://docs.shipium.com/docs/specifying-carrier-service-and-method) and a list of `carrierServiceMethodIds` in [Supported Carriers](https://docs.shipium.com/docs/supported-carriers). |
| `ltlShipmentParameters.fulfillmentContextIds` | **Type:** String
**Description:** A collection of [fulfillment context](https://docs.shipium.com/docs/fulfillment-contexts) IDs or fulfillment context aliases to use in the fulfillment context detail search for LTL carrier selection; there must be exactly one fulfillment context that can ship from the origin to the destination, for the specified tenant, regardless of whether or not this list is populated. |
| `ltlShipmentParameters.fulfillmentType` | **Type:** String (enumeration)
**Values:**`at_large`, `customer`, `hundredweight`, `reship`, `returns`, `unknown`
**Description:** The [fulfillment methodology](https://docs.shipium.com/docs/fulfillment-contexts#context-details) of the shipment |
| `ltlShipmentParameters.pricingTypes` | **Type:** Array of strings (enumeration) **Values:**`all`, `contract`, `contractPallet`, `dynamic`, `volume`, `unknown`
**Description:** The type of pricing for the LTL shipment; the default value is `all`. |
| `ltlShipmentParameters.serviceLevels` | **Type:** Array of strings (enumeration) **Values:**`all`, `guaranteedMorning`, `guaranteedNoon`, `guaranteedEndOfDay`, `standard`, `unknown`
**Description:** The time-definite delivery options that should be eligible for LTL carrier selection; the default value is `standard`. |
| `ltlShipmentParameters.accessorialCodes` | **Type:** Array of strings (enumeration)
**Values:** For a full list of values and details, see [LTL Accessorial Codes](https://docs.shipium.com/docs/ltl-less-than-truckload-apis#ltl-accessorial-codes) .
**Description:** Any optional requested accessorial services will be passed to the carrier. |
### ltlShipmentParameters.billToContact fields [Skip link to ltlShipmentParameters.billToContact fields](https://docs.shipium.com/docs/ltl-shipment-cost-compare-api\#ltlshipmentparametersbilltocontact-fields)
The bill-to-contact fields refer to the entity that should be billed for the LTL shipment; by default, the [carrier contracts](https://docs.shipium.com/docs/carrier-contracts) in the [fulfillment context](https://docs.shipium.com/docs/fulfillment-contexts) will be used for billing. Either the `addressLineComponents` or the other address fields should be provided.
#### Required fields [Skip link to Required fields](https://docs.shipium.com/docs/ltl-shipment-cost-compare-api\#required-fields-4)
| Field | Details |
| --- | --- |
| `ltlShipmentParameters.billToContact.countryCode` | **Type:** String
**Description:** The ISO 3166-1 [country code](https://docs.shipium.com/docs/non-us-address-formats) for the entity that should be billed for the LTL shipment |
| `ltlShipmentParameters.billToContact.postalCode` | **Type:** String
**Description:** A country-code-appropriate postal code for the entity that should be billed for the LTL shipment |
| `ltlShipmentParameters.billToContact .thirdPartyBillingSetId` | **Type:** String
**Required when**`billToContact` is included
**Description:** Either the Shipium-generated or your own unique [third party billing](https://docs.shipium.com/docs/bill-a-third-party) set ID; this value is used to look up the account number each LTL carrier uses to determine pricing agreement. |
#### Optional fields [Skip link to Optional fields](https://docs.shipium.com/docs/ltl-shipment-cost-compare-api\#optional-fields-5)
| Field | Details |
| --- | --- |
| `ltlShipmentParameters.billToContact.addressType` | **Type:** String (enumeration)
**Values:**`commercial`, `residential`
**Description:** The type of location for the entity that should be billed for the LTL shipment |
| `ltlShipmentParameters.billToContact.city` | **Type:** String
**Description:** The name of the city for the entity that should be billed for the LTL shipment |
| `ltlShipmentParameters.billToContact.company` | **Type:** String
**Description:** The company name for the entity that should be billed for the LTL shipment |
| `ltlShipmentParameters.billToContact.emailAddress` | **Type:** String
**Description:** The email address of the entity that should be billed for the LTL shipment |
| `ltlShipmentParameters.billToContact.name` | **Type:** String
**Description:** The name of the contact for the entity that should be billed for the LTL shipment |
| `ltlShipmentParameters.billToContact.phoneNumber` | **Type:** String
**Description:** The phone number of the entity that should be billed for the LTL shipment |
| `ltlShipmentParameters.billToContact .phoneNumberCountryCode` | **Type:** String
**Description:** The phone number country code of the entity that should be billed for the LTL shipment |
| `ltlShipmentParameters.billToContact.state` | **Type:** String
**Description:** The 2-letter postal abbreviation of the state for the entity that should be billed for the LTL shipment |
| `ltlShipmentParameters.billToContact.street1` | **Type:** String
**Description:** The first address line for the entity that should be billed for the LTL shipment |
| `ltlShipmentParameters.billToContact.street2` | **Type:** String
**Description:** The second address line for the entity that should be billed for the LTL shipment |
### ltlShipmentParameters.collectOnDelivery fields [Skip link to ltlShipmentParameters.collectOnDelivery fields](https://docs.shipium.com/docs/ltl-shipment-cost-compare-api\#ltlshipmentparameterscollectondelivery-fields)
#### Conditional fields [Skip link to Conditional fields](https://docs.shipium.com/docs/ltl-shipment-cost-compare-api\#conditional-fields-3)
| Field | Details |
| --- | --- |
| `ltlShipmentParameters.collectOnDelivery.amount` | **Type:** Number (float)
**Example:**`12.34`
**Condition:** Required if including `collectOnDelivery`
**Description:** The amount of money |
| `ltlShipmentParameters.collectOnDelivery.currency` | **Type:** String
**Example:**`usd`
**Condition:** Required if including `collectOnDelivery`
**Description:** The [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code of the amount of money; this is required unless a default currency unit is supplied elsewhere. If this and a default are both supplied, this will take priority. |
### ltlShipmentParameters.hazmatContact fields [Skip link to ltlShipmentParameters.hazmatContact fields](https://docs.shipium.com/docs/ltl-shipment-cost-compare-api\#ltlshipmentparametershazmatcontact-fields)
#### Conditional fields [Skip link to Conditional fields](https://docs.shipium.com/docs/ltl-shipment-cost-compare-api\#conditional-fields-4)
| Field | Details |
| --- | --- |
| `ltlShipmentParameters.hazmatContact.contactName` | **Type:** String
**Condition:** Required if including `hazmatContact`
**Description:** The name of the contact to use as the return-to contact if the package is being returned |
| `ltlShipmentParameters.hazmatContact.phoneNumber` | **Type:** String
**Condition:** Required if including `hazmatContact`
**Description:** The phone number of the contact to use as the return-to contact if the package is being returned |
#### Optional fields [Skip link to Optional fields](https://docs.shipium.com/docs/ltl-shipment-cost-compare-api\#optional-fields-6)
| Field | Details |
| --- | --- |
| `ltlShipmentParameters.hazmatContact .phoneNumberCountryCode` | **Type:** String
**Description:** The phone number country code of the contact to use as the return-to contact if the package is being returned |
| `ltlShipmentParameters.hazmatContact.email` | **Type:** String
**Description:** The email of the contact to use as the return-to contact if the package is being returned |
### ltlShipmentParameters.packagingOptions fields [Skip link to ltlShipmentParameters.packagingOptions fields](https://docs.shipium.com/docs/ltl-shipment-cost-compare-api\#ltlshipmentparameterspackagingoptions-fields)
#### Conditional fields [Skip link to Conditional fields](https://docs.shipium.com/docs/ltl-shipment-cost-compare-api\#conditional-fields-5)
| Field | Details |
| --- | --- |
| `ltlShipmentParameters.packagingOptions .loadPackagingType` | **Type:** String (enumeration)
**Values:**`loose`, `overboxed`, `piece`, `wrapped`, `pallet`
**Condition:** Required if there are any `existingShipmentIds` or `shipments` in the `LtlCostRequest`
**Description:** How the packages in the load will be packaged together |
| `ltlShipmentParameters.packagingOptions .loadPackagingSize.height` | **Type:** Number (float)
**Example:**`84`
**Condition:** Required if there are any `existingShipmentIds` or `shipments` in the `LtlCostRequest`
**Description:** The maximum height that packages can be stacked within the packaging |
| `ltlShipmentParameters.packagingOptions .loadPackagingSize.length` | **Type:** Number (float)
**Example:**`48`
**Condition:** Required if there are any `existingShipmentIds` or `shipments` in the `LtlCostRequest`
**Description:** The longer horizontal dimension that packages can occupy within the packaging |
| `ltlShipmentParameters.packagingOptions .loadPackagingSize.linearUnit` | **Type:** String (enumeration)
**Values:**`in` (inch), `cm` (centimeter)
**Condition:** Required if there are any `existingShipmentIds` or `shipments` in the `LtlCostRequest`
**Description:** The unit of measure for linear dimensions (length, width, height) |
| `ltlShipmentParameters.packagingOptions .loadPackagingSize.maximumWeight` | **Type:** Number (float)
**Example:**`850.25`
**Condition:** Required if there are any `existingShipmentIds` or `shipments` in the `LtlCostRequest`
**Description:** The maximum weight of packages within the packaging. If not specified, no maximum weight will be used when determining how to pack packages. |
| `ltlShipmentParameters.packagingOptions .loadPackagingSize.packagingWeight` | **Type:** Number (float)
**Example:**`10.125`
**Condition:** Required if there are any `existingShipmentIds` or `shipments` in the `LtlCostRequest`
**Description:** The weight of the packaging without any packages |
| `ltlShipmentParameters.packagingOptions .loadPackagingSize.weightUnit` | **Type:** String (enumeration)
**Values:**`g` (gram), `kg` (kilogram), `oz` (ounce), `lb` (pound)
**Condition:** Required if there are any `existingShipmentIds` or `shipments` in the `LtlCostRequest`
**Description:** The unit of measure for maximum weight of packages within the packaging, and the packaging itself |
| `ltlShipmentParameters.packagingOptions .loadPackagingSize.width` | **Type:** Number (float)
**Example:**`40`
**Condition:** Required if there are any `existingShipmentIds` or `shipments` in the `LtlCostRequest`
**Description:** The shorter horizontal dimension that packages can occupy within the packaging |
### packedShipments fields [Skip link to packedShipments fields](https://docs.shipium.com/docs/ltl-shipment-cost-compare-api\#packedshipments-fields)
#### Required fields [Skip link to Required fields](https://docs.shipium.com/docs/ltl-shipment-cost-compare-api\#required-fields-5)
| Field | Details |
| --- | --- |
| `packedShipments.loadPackagingSize.height` | **Type:** Number (float)
**Example:**`84`
**Description:** The height that packages are stacked within the packaging |
| `packedShipments.loadPackagingSize.length` | **Type:** Number (float)
**Example:**`48`
**Description:** The longer horizontal dimension that packages occupy within the packaging |
| `packedShipments.loadPackagingSize.linearUnit` | **Type:** String (enumeration)
**Values:**`in` (inch), `cm` (centimeter)
**Description:** The unit of measure for linear dimensions (length, width, height) |
| `packedShipments.loadPackagingSize.weight` | **Type:** Number (float)
**Example:**`850.25`
**Description:** The total weight of packages within the packaging |
| `packedShipments.loadPackagingSize.weightUnit` | **Type:** String (enumeration)
**Values:**`g` (gram), `kg` (kilogram), `oz` (ounce), `lb` (pound)
**Description:** The unit of measure for weight of the packages within the packaging |
| `packedShipments.loadPackagingSize.width` | **Type:** Number (float)
**Example:**`40`
**Description:** The shorter horizontal dimension that packages occupy within the packaging |
| `packedShipments.nmfcFreightClass` | **Type:** String
**Description:** A string representing the broad class of products being shipped in this load; this should be the largest (i.e., 51 > 50) NMFC class of any of the products in the load. For example, both bricks and steel pipes have an NMFC class of 50. |
#### Conditional fields [Skip link to Conditional fields](https://docs.shipium.com/docs/ltl-shipment-cost-compare-api\#conditional-fields-6)
| Field | Details |
| --- | --- |
| `packedShipments.declaredValue.amount` | **Type:** Number (float)
**Example:**`12.34`
**Condition:** Required if including `declaredValue`
**Description:** The amount of money that should be paid by the recipient upon delivery of the package |
| `packedShipments.declaredValue.currency` | **Type:** String
**Example:**`usd`
**Condition:** Required if a currency amount is not provided elsewhere
**Description:** The [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code of the amount of money that should be paid by the recipient upon delivery of the package |
#### Optional fields [Skip link to Optional fields](https://docs.shipium.com/docs/ltl-shipment-cost-compare-api\#optional-fields-7)
| Field | Details |
| --- | --- |
| `packedShipments.loadPackagingType` | **Type:** String (enumeration)
**Values:**`loose`, `overboxed`, `piece`, `wrapped`, `pallet`
**Description:** How the packages in the load are packaged together |
### shipments fields [Skip link to shipments fields](https://docs.shipium.com/docs/ltl-shipment-cost-compare-api\#shipments-fields)
#### Optional fields [Skip link to Optional fields](https://docs.shipium.com/docs/ltl-shipment-cost-compare-api\#optional-fields-8)
| Field | Details |
| --- | --- |
| `shipments.carrierProcessingId` | **Type:** String
**Description:** A carrier-provided identifier, supplied when it is needed to process the shipment |
| `shipments.deliveryNote` | **Type:** String
**Description:** A string passed to carriers for a delivery note |
| `shipments.partnerReferenceIdentifier` | **Type:** String
**Description:** An optional identifier your organization passes to the carrier for reference |
| `shipments.partnerReferenceIdentifier2` | **Type:** String
**Description:** A second optional identifier your organization passes to the carrier for reference |
| `shipments.purchaseOrderIdentifier` | **Type:** String
**Description:** A string passed to the carrier as a purchase order identifier |
| `shipments.referenceIdentifier` | **Type:** String
**Description:** An optional string [identifier](https://docs.shipium.com/docs/reference-fields-and-carrier-mappings) passed to the carrier (`referenceIdentifier`, `referenceIdentifier2`, `referenceIdentifier3`, `referenceIdentifier4`, `referenceIdentifier5`) |
| `shipments.shipmentTags` | **Type:** String
**Description:** A collection of free-form tags that may be added to this shipment |
| `shipments.orderedDateTime` | **Type:** String (date-time)
**Example:**`2019-10-29T09:12:33.123456Z`
**Description:** The [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) timestamp for when the customer placed an order for this product |
| `shipments.partnerShipmentId` | **Type:** String
**Example:**`myCustomPartnerShipmentId123`
**Description:** An optional unique identifier that may be used for this shipment |
### shipments.packages fields [Skip link to shipments.packages fields](https://docs.shipium.com/docs/ltl-shipment-cost-compare-api\#shipmentspackages-fields)
#### Required fields [Skip link to Required fields](https://docs.shipium.com/docs/ltl-shipment-cost-compare-api\#required-fields-6)
| Field | Details |
| --- | --- |
| `shipments.packages.packageReferenceIdentifier` | **Type:** String
**Description:** Used to correlate packages to label documents from the carrier |
### Optional fields [Skip link to Optional fields](https://docs.shipium.com/docs/ltl-shipment-cost-compare-api\#optional-fields-9)
| Field | Details |
| --- | --- |
| `shipments.packages.partnerProvidedPackageId` | **Type:** String
**Description:** A custom identifier your organization assigns to the packaging |
| `shipments.packages.deliveredDateTime` | **Type:** String (date-time)
**Example:**`2019-10-31T10:50:11.123456Z`
**Description:** The [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) timestamp for when the package was delivered to the customer |
## shipments.packages.orderItemQuantities fields [Skip link to shipments.packages.orderItemQuantities fields](https://docs.shipium.com/docs/ltl-shipment-cost-compare-api\#shipmentspackagesorderitemquantities-fields)
### Required fields [Skip link to Required fields](https://docs.shipium.com/docs/ltl-shipment-cost-compare-api\#required-fields-7)
| Field | Details |
| --- | --- |
| `shipments.packages.orderItemQuantities.nmfcFreightClass` | **Type:** String
**Description:** Required for LTL shipments, a string representing the broad class of product being shipped; for example, both bricks and steel pipes have an NMFC class of 50. |
| `shipments.packages.orderItemQuantities.productId` | **Type:** String
**Example:**`RN03947--Z43121`
**Description:** A product ID for the product being checked (ISBN, UPC, etc.) |
| `shipments.packages.orderItemQuantities.quantity` | **Type:** Integer (int32)
**Example:**`3`
**Description:** The number of units of the product |
### Conditional fields [Skip link to Conditional fields](https://docs.shipium.com/docs/ltl-shipment-cost-compare-api\#conditional-fields-7)
| Field | Details |
| --- | --- |
| `shipments.packages.orderItemQuantities.productDetails` | **Type:** Array of strings
**Values:**`limited_quantity` (preferred for LQ/ORM-D; alias: `lq`), `bound_printed_matter` (alias: `bpm`), `perishable`, `ormd` (legacy; alias: `orm-d`)
**Condition:** Required for [international shipments](https://docs.shipium.com/docs/customs-info-api-example-definitions) and shipments containing [hazardous materials](https://docs.shipium.com/docs/hazardous-materials-support)
**Description:** A list of product properties that affect carrier selection and handling; see [productDetails Reference](https://docs.shipium.com/docs/hazardous-materials-support#productdetails-reference) for details. |
#### Optional fields [Skip link to Optional fields](https://docs.shipium.com/docs/ltl-shipment-cost-compare-api\#optional-fields-10)
| Field | Details |
| --- | --- |
| `shipments.packages.orderItemQuantities .deliveryEstimateId` | **Type:** String
**Example:**`0b3d140a-525b-43a7-896c-cdc381580d61`
**Description:** A delivery estimate ID associated with the product |
| `shipments.packages.orderItemQuantities .orderItemReferenceIdentifier` | **Type:** String
**Example:**`someIdentifier`
**Description:** An external identifier that can reference the order item that exists in an external order management system; this field will be passed to supported carriers. |
| `shipments.packages.orderItemQuantities .shipiumOrderId` | **Type:** String
**Example:**`4dc43fff-c3af-4d7b-8a18-e01f2b4cb312`
**Description:** Identification used to represent the group of delivery estimates purchased |
| `shipments.packages.orderItemQuantities .partnerOrderId` | **Type:** String
**Example:**`myCustomPartnerOrderId123`
**Description:** A unique identifier supplied by your organization representing this order |
| `shipments.packages.orderItemQuantities .hazmat` | **Type:** Boolean
**Values:**`true` or `false`
**Description:** If `true`, this indicates that the item is [hazardous material](https://docs.shipium.com/docs/hazardous-materials-support) (hazmat). The default value is `false`. |
| `shipments.packages.orderItemQuantities .productTaxCode` | **Type:** String
**Description:** The tax code that applies to the given product |
| `shipments.packages.orderItemQuantities .nmfcCode` | **Type:** String
**Description:** Useful for LTL shipments, a string representing the narrow type of product being shipped; for example, bricks have an NMFC code of 32100.2 and steel pipes have an NMFC code of 51200. |
### shipments.packages.orderItemQuantities.hazmatInfo fields [Skip link to shipments.packages.orderItemQuantities.hazmatInfo fields](https://docs.shipium.com/docs/ltl-shipment-cost-compare-api\#shipmentspackagesorderitemquantitieshazmatinfo-fields)
For information on shipping hazmat items, see [Hazardous Materials](https://docs.shipium.com/docs/hazardous-materials-support).
#### Conditional fields [Skip link to Conditional fields](https://docs.shipium.com/docs/ltl-shipment-cost-compare-api\#conditional-fields-8)
| Field | Details |
| --- | --- |
| `shipments.packages.orderItemQuantities .hazmatInfo.category` | **Type:** String (enumeration)
**Values:**`defined`, `aerosols_flammable`, `contains_lithium_ion`, `packaged_lithium_ion`, `lithium_ion_battery_only`, `contains_lithium_metal`, `packaged_lithium_metal`, `lithium_metal_battery_only`, `dry_ice`
**Condition:** Required if including `hazmatInfo`
**Description:** Hazmat category for this order item; use `defined` to specify detailed information. |
| `shipments.packages.orderItemQuantities .hazmatInfo.quantity` | **Type:** Number (float)
**Example:**`2.1`
**Condition:** Required if `category` is defined
**Description:** The amount of quantity type material in quantity units |
| `shipments.packages.orderItemQuantities .hazmatInfo.quantityType` | **Type:** String (enumeration)
**Values:**`gross`, `net`
**Condition:** Required if `category` is defined
**Description:** Determines whether the quantity includes the raw material (net) or also includes the material housing (gross) |
| `shipments.packages.orderItemQuantities .hazmatInfo.quantityUnits` | **Type:** String (enumeration)
**Values:**`g` (gram), `kg` (kilogram), `lb` (pound), `oz` (ounce), `ml` (milliliter), `l` (liter)
**Condition:** Required if `category` is defined
**Description:** The unit of measure for the quantity of hazardous materials specified |
| `shipments.packages.orderItemQuantities .hazmatInfo.containerType` | **Type:** String (enumeration)
**Values:**`fiberboard_box`, `wooden_box`, `plastic_jerrican`, `metal_box`, `steel_drum`, `other`, `plastic_box`, `plastic_drum`, `styrofoam_box`, `cylinder`, `envirotainer`, `plywood_box`, `aluminum_drum`, `aluminum_cylinder`, `plastic_pail`, `plywood_drum`, `fiber_drum`, `steel_jerrican`, `aluminum_jerrican`, `steel_box`, `carton`, `aluminum_box`
**Condition:** Required if `category` is defined
**Description:** The material in which the hazardous material is packaged |
| `shipments.packages.orderItemQuantities .hazmatInfo.hazmatId` | **Type:** String
**Example:**`UN1755`
**Condition:** Required if `category` is defined
**Description:** The International Air Transport Association (IATA) or U.S. Department of Transportation (DOT) regulatory identifier for the commodity as appropriate |
| `shipments.packages.orderItemQuantities .hazmatInfo.properShippingName` | **Type:** String
**Example:**`chromic acid solution`
**Condition:** Required if `category` is defined
**Description:** Proper shipping name that is associated with the specified hazmat ID |
| `shipments.packages.orderItemQuantities .hazmatInfo.transportMode` | **Type:** String (enumeration)
**Values:**`ground`, `passenger_and_cargo_aircraft`, `cargo_aircraft_only`
**Condition:** Required if `category` is defined
**Description:** Declares that a package was prepared according to ground, passenger aircraft, or cargo aircraft only |
| `shipments.packages.orderItemQuantities .hazmatInfo.hazardClass` | **Type:** String (enumeration)
**Values:**`class_1_explosive`, `class_2_flammable_gas`, `class_3_flammable_liquid`, `class_4_flammable_solid`, `class_5_organic_peroxide`, `class_6_poisonous_material`, `class_7_radioactive`, `class_8_corrosive_material`, `class_9_miscellaneous`
**Condition:** Required if `category` is defined
**Description:** The hazard class of the hazmat |
#### Optional fields [Skip link to Optional fields](https://docs.shipium.com/docs/ltl-shipment-cost-compare-api\#optional-fields-11)
| Field | Details |
| --- | --- |
| `shipments.packages.orderItemQuantities .hazmatInfo.packingGroup` | **Type:** String (enumeration)
**Values:**`i`, `ii`, `iii`
**Description:** The packing group code for the hazardous material |
| `shipments.packages.orderItemQuantities .hazmatInfo.packingInstructionCode` | **Type:** String
**Example:**`967`
**Description:** The packing instruction code used for air transport |
| `shipments.packages.orderItemQuantities .hazmatInfo.subsidiaryClasses` | **Type:** String
**Example:**`8.1`
**Description:** The appropriate IATA/DOT subsidiary classes associated with the material and the hazard class |
### shipments.packages.packagingType fields [Skip link to shipments.packages.packagingType fields](https://docs.shipium.com/docs/ltl-shipment-cost-compare-api\#shipmentspackagespackagingtype-fields)
#### Conditional fields [Skip link to Conditional fields](https://docs.shipium.com/docs/ltl-shipment-cost-compare-api\#conditional-fields-9)
| Field | Details |
| --- | --- |
| `shipments.packages.packagingType .packagingMaterial` | **Type:** String (enumeration)
**Values:**`box`, `envelope`, `flat_pack`, `mailing_tube`, `parcel_pallet`
**Condition:** Required when `packagingTypeId` is not provided. Optional when `packagingTypeId` is provided; in this case, the value from the request will be used if the `packagingMaterial` is not defined in the pre-configured packaging associated with the `packagingTypeId`.
**Description:** The material type of the packaging |
| `shipments.packages.packagingType .packagingTypeId` | **Type:** String
**Example:**`ebd94f8b-d390-4c9c-987f-b88343f5bf45`
**Condition:** When provided, `linearDimensions` and `packagingMaterial` become optional. When absent, `linearDimensions` and `packagingMaterial` are required.
**Description:** The unique identifier for a [pre-configured packaging](https://docs.shipium.com/docs/configure-packaging-configuration) type defined in the Shipium Console. When provided, the system uses the pre-configured packaging properties (dimensions, material, weight) associated with this ID. |
| `shipments.packages.packagingType .linearDimensions.linearUnit` | **Type:** String (enumeration)
**Values:**`cm` (centimeter), `in` (inch)
**Condition:** Required when `packagingTypeId` is not provided. Optional when `packagingTypeId` is provided; in this case, the value from the request will be used if dimensions are not defined in the [pre-configured packaging](https://docs.shipium.com/docs/configure-packaging-configuration).
**Description:** The unit in which linear dimensions are provided |
| `shipments.packages.packagingType .linearDimensions.length` | **Type:** Number (float)
**Example:**`13`
**Condition:** Required when `packagingTypeId` is not provided. Optional when `packagingTypeId` is provided; in this case, the value from the request will be used if dimensions are not defined in the [pre-configured packaging](https://docs.shipium.com/docs/configure-packaging-configuration).
**Description:** The longest linear dimension (i.e., the longest side of a box or envelope) |
| `shipments.packages.packagingType .linearDimensions.width` | **Type:** Number (float)
**Example:**`12`
**Condition:** Required when `packagingTypeId` is not provided. Optional when `packagingTypeId` is provided; in this case, the value from the request will be used if dimensions are not defined in the [pre-configured packaging](https://docs.shipium.com/docs/configure-packaging-configuration).
**Description:** The second longest linear dimension (i.e., the second longest side of a box or envelope) |
| `shipments.packages.packagingType .linearDimensions.height` | **Type:** Number (float)
**Example:**`10`
**Condition:** Required when `packagingTypeId` is not provided. Optional when `packagingTypeId` is provided; in this case, the value from the request will be used if dimensions are not defined in the [pre-configured packaging](https://docs.shipium.com/docs/configure-packaging-configuration).
**Description:** The least long linear dimension (i.e., the shortest side of a box or envelope) **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. |
#### Optional fields [Skip link to Optional fields](https://docs.shipium.com/docs/ltl-shipment-cost-compare-api\#optional-fields-12)
| Field | Details |
| --- | --- |
| `shipments.packages.packagingType .packagingSizeName` | **Type:** String
**Example:**`13x12x10 box`
**Description:** A custom name for the packaging |
| `shipments.packages.packagingType .packagingWeight.weightUnit` | **Type:** String (enumeration)
**Values:**`g` (gram), `kg` (kilogram), `lb` (pound), `oz` (ounce)
**Description:** The unit in which weight values are provided |
| `shipments.packages.packagingType .packagingWeight.weight` | **Type:** Number (float)
**Example:**`50`
**Description:** The value of the weight |
### shipments.packages.totalWeight fields [Skip link to shipments.packages.totalWeight fields](https://docs.shipium.com/docs/ltl-shipment-cost-compare-api\#shipmentspackagestotalweight-fields)
All fields in this object are optional.
| Field | Details |
| --- | --- |
| `shipments.packages.totalWeight.weightUnit` | **Type:** String (enumeration)
**Values:**`g` (gram), `kg` (kilogram), `lb` (pound), `oz` (ounce)
**Description:** The unit in which weight values are provided |
| `shipments.packages.totalWeight.weight` | **Type:** Number (float)
**Example:**`50`
**Description:** The value of the weight of this type of empty packaging |
### shipments.packages.totalDeclaredValue fields [Skip link to shipments.packages.totalDeclaredValue fields](https://docs.shipium.com/docs/ltl-shipment-cost-compare-api\#shipmentspackagestotaldeclaredvalue-fields)
All fields in this object are optional.
| Field | Details |
| --- | --- |
| `shipments.packages.totalDeclaredValue.declaredValue` | **Type:** Number (float)
**Description:** The total monetary amount of the declared value for the package |
| `shipments.packages.totalDeclaredValue.currencyCode` | **Type:** String
**Example:**`usd`
**Description:** The [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code for the declared value |
### packageShipmentParameters fields [Skip link to packageShipmentParameters fields](https://docs.shipium.com/docs/ltl-shipment-cost-compare-api\#packageshipmentparameters-fields)
These are parameters for small package carrier selection comparison. All fields in this object are optional.
| Field | Details |
| --- | --- |
| `packageShipmentParameters .carrierServiceMethodAllowList` | **Type:** Array of strings
**Description:** A list of `carrierServiceMethodIds` and/or carriers that should be considered for package carrier selection; you can find more information in [Specify Carrier Service and Method](https://docs.shipium.com/docs/specifying-carrier-service-and-method) and a list of `carrierServiceMethodIds` in [Supported Carriers](https://docs.shipium.com/docs/supported-carriers). |
| `packageShipmentParameters .deliverySignatureOption` | **Type:** String (enumeration)
**Values:**`AdultResidentSignature`, `AdultSignature`, `None`, `ResidentSignature`, `Signature`, `Unknown`
**Description:** A [delivery signature option](https://docs.shipium.com/docs/shipment-special-processing-properties) passed in the API request; the default value is `none`. |
| `packageShipmentParameters.deliveryWindow` | **Type:** Object
**Description:** The delivery timeframe |
| `packageShipmentParameters .forceThirdPartyBilling` | **Type:** Boolean
**Values:**`true` or `false`
**Description:** If `true`, this indicates that [third party billing](https://docs.shipium.com/docs/bill-a-third-party) is a requirement for this shipment. No service method should be selected that does not support third party billing. |
| `packageShipmentParameters .fulfillmentContextIds` | **Type:** Array of strings
**Description:** A collection of [fulfillment context](https://docs.shipium.com/docs/fulfillment-contexts) IDs or fulfillment context aliases to use in the fulfillment context detail search for package carrier selection; there must be exactly one fulfillment context that can ship from the origin to the destination, for the specified tenant, regardless of whether or not this list is populated. |
| `packageShipmentParameters.fulfillmentType` | **Type:** String (enumeration)
**Values:**`at_large`, `customer`, `hundredweight`, `reship`, `returns`
**Description:** The [fulfillment methodology](https://docs.shipium.com/docs/fulfillment-contexts#context-details) of the shipment |
| `packageShipmentParameters .ignoreCarrierMinimumDimensions` | **Type:** Boolean
**Values:**`true` or `false`
**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 carrier selection. The default value is `false`. |
| `packageShipmentParameters .ignoreUpgradeSpendLimits` | **Type:** Boolean
**Values:**`true` or `false`
**Description:** When `true`, this indicates that this shipment can ignore all your organization's configured upgrade limits for the potential upgrade required to deliver the shipment by the [desired delivery date](https://docs.shipium.com/docs/desired-and-exact-delivery-dates). The default value is `false`. |
| `packageShipmentParameters .includeInjectionProfiles` | **Type:** Boolean
**Values:**`true` or `false`
**Description:** When `true`, service methods from the configured injection profiles will be considered during carrier selection. The default value is `true`. |
| `packageShipmentParameters.pickupWindow` | **Type:** Object
**Description:** The timeframe for the delivery pickup |
| `packageShipmentParameters .preferredCarrierDeliveryDateTime` | **Type:** String (date-time)
**Example:**`2019-10-31T20:00:00Z`
**Description:** The [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) date-time the package is intended to arrive to the customer; this will be passed through to the carrier. |
| `packageShipmentParameters.saturdayDelivery` | **Type:** Boolean
**Values:**`true` or `false`
**Description:** If you pass `saturdayDelivery`, you can specify whether or not you want [Saturday delivery](https://docs.shipium.com/docs/weekend-and-holiday-delivery) to be an option for this package. The default value is `false`.
**Note:** This does not guarantee a Saturday delivery. |
| `packageShipmentParameters .serviceMethodPoBoxAllowList` | **Type:** Array of strings
**Description:** A list of `serviceMethodIds` 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 `serviceMethodIds` in [Supported Carriers](https://docs.shipium.com/docs/supported-carriers). |
| `packageShipmentParameters.shipOption` | **Type:** String
**Example:**`standard`
**Description:** A high-level [shipping option](https://docs.shipium.com/docs/shipment-ship-option-overview) shown to or selected by a customer; this is only applicable when calculating the package carrier selection for this item. |
| `packageShipmentParameters .thirdPartyBillingSetId` | **Type:** String
**Description:** Either the Shipium [third party billing](https://docs.shipium.com/docs/bill-a-third-party) set ID or the third party billing set ID provided by your organization; when present, this is used to indicate the third party billing set that should be used for the billing of the shipment. |
### packageShipmentParameters.injectionParameters fields [Skip link to packageShipmentParameters.injectionParameters fields](https://docs.shipium.com/docs/ltl-shipment-cost-compare-api\#packageshipmentparametersinjectionparameters-fields)
#### Conditional fields [Skip link to Conditional fields](https://docs.shipium.com/docs/ltl-shipment-cost-compare-api\#conditional-fields-10)
| Field | Details |
| --- | --- |
| `packageShipmentParameters.injectionParameters .injectionProfileId` | **Type:** String
**Condition:** Required when including `injectionSiteId`
**Description:** The Shipium ID or your organization's unique ID for an [injection](https://docs.shipium.com/docs/injection) profile that should be considered during carrier selection |
#### Optional fields [Skip link to Optional fields](https://docs.shipium.com/docs/ltl-shipment-cost-compare-api\#optional-fields-13)
| Field | Details |
| --- | --- |
| `packageShipmentParameters.injectionParameters .injectionSiteId` | **Type:** String
**Description:** The Shipium ID or your organization's unique ID for an [injection](https://docs.shipium.com/docs/injection) site that should be considered during carrier selection; if an `injectionSiteId` is specified, it must be accompanied by an `injectionProfileId`. |
### packageShipmentParameters.lastMileDeliveryOptions fields [Skip link to packageShipmentParameters.lastMileDeliveryOptions fields](https://docs.shipium.com/docs/ltl-shipment-cost-compare-api\#packageshipmentparameterslastmiledeliveryoptions-fields)
All fields in this object are optional.
| Field | Details |
| --- | --- |
| `packageShipmentParameters.lastMileDeliveryOptions .deliveryInstruction` | **Type:** String (enumeration)
**Values:**`leave_at_door`, `meet_at_door`
**Description:** Instructions passed to the carrier on how to handle on delivery |
| `packageShipmentParameters.lastMileDeliveryOptions .undeliverableInstruction` | **Type:** String (enumeration)
**Values:**`leave_at_door`, `return`, `destroy`
**Description:** Instructions passed to the carrier on how to handle packages that go undelivered |
| `packageShipmentParameters.lastMileDeliveryOptions .tip.type` | **Type:** String (enumeration)
**Values:**`fixed`, `percentage`
**Description:** The type of tip |
| `packageShipmentParameters.lastMileDeliveryOptions .tip.value` | **Type:** Number (float)
**Description:** The fixed amount or percentage value for the tip |
| `packageShipmentParameters.lastMileDeliveryOptions .tip.currency` | **Type:** String
**Example:**`usd`
**Description:** The currency of the tip amount |
| `packageShipmentParameters.lastMileDeliveryOptions .tipForLabelCreate.type` | **Type:** String (enumeration)
**Values:**`fixed`, `percentage`
**Description:** The type of tip |
| `packageShipmentParameters.lastMileDeliveryOptions .tipForLabelCreate.value` | **Type:** Number (float)
**Description:** The fixed amount or percentage value for the tip |
| `packageShipmentParameters.lastMileDeliveryOptions .tipForLabelCreate.currency` | **Type:** String
**Example:**`usd`
**Description:** The currency of the tip amount |
| `packageShipmentParameters.lastMileDeliveryOptions .deliverableActionForLabelCreate` | **Type:** String (enumeration)
**Values:**`leave_at_door`, `meet_at_door`, `return`, `discard`
**Description:** Instructions passed to the carrier on the label for how to handle on delivery |
| `packageShipmentParameters.lastMileDeliveryOptions .undeliverableActionForLabelCreate` | **Type:** String (enumeration)
**Values:**`leave_at_door`, `meet_at_door`, `return`, `discard`
**Description:** Instructions passed to the carrier on the label for how to handle packages that go undelivered |
### Response attributes [Skip link to Response attributes](https://docs.shipium.com/docs/ltl-shipment-cost-compare-api\#response-attributes)
The primary response attributes of the LTL Shipment Cost Compare API are described in the following table. Elements included in the above request table that are also returned in the API response are not included here.
| Response attribute | Description |
| --- | --- |
| `shipiumLtlCostId` | The Shipium-generated unique ID of the LTL cost, for reference |
| `partnerLtlCostId` | An optional unique identifier that may be used for this LTL cost |
| `rawDesiredDeliveryDate` | The timestamp passed in by your organization (or your fulfillment partner) for the intended date the package will arrive to the customer; the timestamp must be a valid ISO 8601 timestamp. |
| `recommendedTransportationType` | Whether using LTL or small package shipping will be less expensive, and able to meet the request parameters (`ltlTransportation` or `packageTransportation`) |
| `recommendedTransportationTypeCost` | The cost of using the recommended transportation type for this shipment |
| `allTransportationTypeCosts .transportationType` | The transportation type used for this cost estimate (`ltlTransportation` or `packageTransportation`) |
| `allTransportationTypeCosts .transportationTypeCost` | The cost of using this transportation type for the shipment; this will be zero if no carrier could be found for this shipment. |
| `ltlCostDetails.loadPackaging` | How the packages in the LTL shipment are packaged or should be packaged |
| `ltlCostDetails.evaluatedCarriers` | Information about the other carriers that were considered but were not selected because they either can't meet the desired delivery date, can't carry the shipment, can't pick up the shipment on the requested date, or cost more than the selected carrier. This attribute requires `includeEvaluatedServiceMethodsInResponse` to be `true` in the request. |
| `ltlCostDetails.selectedCarrier` | Information about the selected carrier |
| `ltlCostDetails.totalCost` | The least expensive quoted cost of the shipment, using LTL; this will be zero in the case that no carrier could be selected. |
| `ltlShipmentParameters` | Request parameters that informed LTL costing and carrier selection |
| `packageCostDetails.totalCost` | How much it would cost to ship all of the packages individually |
| `packageCostDetails.packageDetails` | Information about each package's carrier selection |
| `packageCostDetails.status` | Summary of what happened during package carrier selection:
- `success` indicates that all packages had a carrier eligible to ship them.
- `failure` indicates that one or more packages had no carriers eligible to ship them.
- `timeout` indicates that one or more carrier selections could not be completed due to the amount of time required to process them. |
| `packageShipmentParameters` | Request parameters that informed package shipments and carrier selection; this information is only present if these parameters were in the cost request. |
| `packedShipments` | The already packed LTL shipments that should be included in this LTL shipment; items in this list are used for LTL costing and do not have their packaging modified, nor are eligible for package carrier selection. Items in this list do not have corresponding Shipium shipments. |
| `shipments` | An array of objects containing `partnerShipmentId` and `shipiumShipmentId` |
## Example cURL call [Skip link to Example cURL call](https://docs.shipium.com/docs/ltl-shipment-cost-compare-api\#example-curl-call)
cURL
```curl
curl --request POST
--url https://api.shipium.com/api/v1/ltl/shipment/costCompare
--header 'accept: application/json'
--header $AUTHSTRING
--header 'content-type: application/json'
--data 'INSERT REQUEST BODY FROM BELOW'
```
## Example request using `shipments` [Skip link to Example request using ,[object Object]](https://docs.shipium.com/docs/ltl-shipment-cost-compare-api\#example-request-using-shipments)
This scenario includes sending full package details in a single API call and getting a side-by-side LTL vs. parcel comparison. This is the most common path for customers evaluating mode selection at the point of shipment.
JSON
```json
{
"shipFromAddress": {
"company": "Harbor Glass Works",
"street1": "4120 Seaport Ave",
"city": "Oakland",
"state": "CA",
"countryCode": "US",
"postalCode": "94607",
"addressType": "commercial"
},
"destinationAddress": {
"company": "Rainier Retail Distribution",
"street1": "8800 Cascade Blvd",
"city": "Kent",
"state": "WA",
"countryCode": "US",
"postalCode": "98032",
"addressType": "commercial"
},
"shipments": [\
{\
"partnerShipmentId": "hgw-order-48201",\
"packages": [\
{\
"packagingType": {\
"packagingMaterial": "box",\
"linearDimensions": {\
"linearUnit": "in",\
"length": 24,\
"width": 18,\
"height": 18\
}\
},\
"totalWeight": {\
"weightUnit": "lb",\
"weight": 145.0\
},\
"orderItemQuantities": [\
{\
"productId": "HGW-VASE-LG-CLR",\
"quantity": 12,\
"nmfcFreightClass": "100",\
"productDescription": "Large clear glass vases"\
}\
]\
}\
]\
}\
],
"ltlShipmentParameters": {
"pickupDate": "2026-04-28",
"pricingTypes": ["contractPallet"],
"accessorialCodes": ["APTD"]
},
"packageShipmentParameters": {
"shipOption": "Standard"
},
"partnerLtlCostId": "harborGlass-compare-2026-04-20-002",
"currencyCode": "usd",
"units": {
"currencyCode": "usd",
"linearUnit": "in",
"weightUnit": "lb"
}
}
```
## Example response using `shipments` [Skip link to Example response using ,[object Object]](https://docs.shipium.com/docs/ltl-shipment-cost-compare-api\#example-response-using-shipments)
In this example, parcel shipping is more economical for this shipment. For multi-pallet loads, LTL typically becomes the more cost-effective choice.
JSON
```json
{
"shipiumLtlCostId": "f2b8c376-0e9c-4a6e-ef1c-7c1bde8f6d9c",
"partnerLtlCostId": "harborGlass-compare-2026-04-20-002",
"partnerTenantId": "harbor-glass-default",
"shipiumTenantId": "9c2e4a18-0d83-4f29-8b71-3e6a5d9c1f04",
"shipFromAddress": {
"company": "Harbor Glass Works",
"street1": "4120 Seaport Ave",
"city": "Oakland",
"state": "CA",
"countryCode": "US",
"postalCode": "94607",
"addressType": "commercial"
},
"shipFromTimeZoneId": "America/Los_Angeles",
"destinationAddress": {
"company": "Rainier Retail Distribution",
"street1": "8800 Cascade Blvd",
"city": "Kent",
"state": "WA",
"countryCode": "US",
"postalCode": "98032",
"addressType": "commercial"
},
"destinationTimeZoneId": "America/Los_Angeles",
"recommendedTransportationType": "packageTransportation",
"recommendedTransportationTypeCost": 189.40,
"testMode": false,
"currencyCode": "usd",
"units": {
"currencyCode": "usd",
"linearUnit": "in",
"weightUnit": "lb"
},
"allTransportationTypeCosts": [\
{\
"transportationType": "ltlTransportation",\
"transportationTypeCost": 298.50\
},\
{\
"transportationType": "packageTransportation",\
"transportationTypeCost": 189.40\
}\
],
"ltlCostDetails": {
"loadPackaging": [\
{\
"details": {\
"loadPackagingType": "pallet",\
"loadPackagingSize": {\
"height": 24,\
"length": 48,\
"width": 40,\
"linearUnit": "in",\
"weight": 145.0,\
"weightUnit": "lb"\
},\
"nmfcFreightClass": "100"\
},\
"shipments": [\
{\
"partnerShipmentId": "hgw-order-48201",\
"shipiumShipmentId": "a3c9d487-1fad-4b7f-f02d-8d2cef9a7eae"\
}\
]\
}\
],
"evaluatedCarriers": [],
"selectedCarrier": {
"billableWeight": {
"weightUnit": "lb",
"weight": 145.0
},
"carrier": "R+L Carriers",
"carrierAccountId": "rl-account-default",
"carrierServiceMethodId": "rl-standard-ltl",
"estimatedDeliveryDate": "2026-05-01T17:00:00Z",
"lineItems": [\
{\
"name": "container",\
"rate": 245.00,\
"lineItemType": "base_rate",\
"nmfcFreightClass": "100",\
"weight": {\
"weightUnit": "lb",\
"weight": 145.0\
}\
},\
{\
"name": "Fuel Surcharge",\
"rate": 38.50,\
"carrierSurchargeId": "FSC",\
"lineItemType": "surcharge"\
},\
{\
"name": "Appointment Required at Delivery",\
"rate": 15.00,\
"carrierSurchargeId": "APTD",\
"lineItemType": "surcharge"\
}\
],
"pickupDateTime": "2026-04-28T16:00:00Z",
"pricingType": "contractPallet",
"quoteId": "rl-quote-7f3e2d91-0428",
"quoteEffectiveDateTime": "2026-04-20T18:30:00Z",
"quoteExpirationDateTime": "2026-04-27T18:30:00Z",
"scacCode": "RLCA",
"serviceLevel": "standard",
"totalCost": 298.50
},
"totalCost": 298.50
},
"ltlShipmentParameters": {
"pickupDate": "2026-04-28",
"pricingTypes": "contractPallet",
"accessorialCodes": "APTD"
},
"packageCostDetails": {
"totalCost": 189.40,
"packageDetails": [\
{\
"status": "success",\
"carrierSelectionId": "cs-8e2a4b71-0428",\
"shipiumShipmentId": "a3c9d487-1fad-4b7f-f02d-8d2cef9a7eae",\
"partnerShipmentId": "hgw-order-48201",\
"partnerId": "harbor-glass",\
"carrierAccountId": "fedex-account-default",\
"serviceMethodIdentifier": "fedex-ground",\
"carrier": "FedEx",\
"carrierServiceMethodId": "fedex-ground",\
"serviceMethodName": "FedEx Ground",\
"totalCost": 189.40,\
"carrierCompareCost": 189.40,\
"carrierInvoiceCost": 189.40,\
"operationalCost": 189.40,\
"thirdPartyBilling": false,\
"carrierSelectionDateTime": "2026-04-20T18:30:00Z",\
"calculatedBillableWeight": {\
"weightUnit": "lb",\
"weight": 145.0\
},\
"evaluatedServiceMethods": [],\
"effectiveShipDateTime": "2026-04-28T16:00:00Z",\
"currencyCode": "usd"\
}\
],
"status": "success"
},
"packageShipmentParameters": {
"shipOption": "Standard"
},
"shipments": [\
{\
"partnerShipmentId": "hgw-order-48201",\
"shipiumShipmentId": "a3c9d487-1fad-4b7f-f02d-8d2cef9a7eae"\
}\
]
}
```
## Example request using `packedShipments` [Skip link to Example request using ,[object Object]](https://docs.shipium.com/docs/ltl-shipment-cost-compare-api\#example-request-using-packedshipments)
This scenario is useful when the load is already palletized or configured. Items in `packedShipments` contribute to the LTL load only and are not included in the parcel comparison. This input method is often combined with `shipments` or `existingShipmentIds` when some items are pre-palletized and others are loose.
JSON
```json
{
"shipFromAddress": {
"company": "Harbor Glass Works",
"street1": "4120 Seaport Ave",
"city": "Oakland",
"state": "CA",
"countryCode": "US",
"postalCode": "94607",
"addressType": "commercial"
},
"destinationAddress": {
"company": "Rainier Retail Distribution",
"street1": "8800 Cascade Blvd",
"city": "Kent",
"state": "WA",
"countryCode": "US",
"postalCode": "98032",
"addressType": "commercial"
},
"packedShipments": [\
{\
"loadPackagingType": "pallet",\
"loadPackagingSize": {\
"height": 60,\
"length": 48,\
"width": 40,\
"linearUnit": "in",\
"weight": 680.0,\
"weightUnit": "lb"\
},\
"nmfcFreightClass": "100",\
"declaredValue": {\
"amount": 4200.00,\
"currency": "usd"\
}\
}\
],
"ltlShipmentParameters": {
"pickupDate": "2026-04-28",
"pricingTypes": ["contractPallet"],
"accessorialCodes": ["APTD"]
},
"packageShipmentParameters": {
"shipOption": "Standard"
},
"partnerLtlCostId": "harborGlass-compare-2026-04-20-003",
"currencyCode": "usd",
"units": {
"currencyCode": "usd",
"linearUnit": "in",
"weightUnit": "lb"
}
}
```
## Example response using `packedShipments` [Skip link to Example response using ,[object Object]](https://docs.shipium.com/docs/ltl-shipment-cost-compare-api\#example-response-using-packedshipments)
This example response shows fields specific to this scenario. The `shipments` example includes the complete response.
JSON
```json
{
"shipiumLtlCostId": "a3c9d487-1fad-4b7f-f02d-8d2cef9a7eae",
"partnerLtlCostId": "harborGlass-compare-2026-04-20-003",
"recommendedTransportationType": "ltlTransportation",
"recommendedTransportationTypeCost": 386.20,
"currencyCode": "usd",
"ltlCostDetails": {
"selectedCarrier": {
"carrier": "R+L Carriers",
"carrierServiceMethodId": "rl-standard-ltl",
"totalCost": 386.20,
"estimatedDeliveryDate": "2026-05-01T17:00:00Z",
"serviceLevel": "standard"
},
"totalCost": 386.20
},
"packageCostDetails": {
"totalCost": 0,
"packageDetails": [],
"status": "success"
}
}
```
Because `packedShipments` items are excluded from parcel comparison, `packageCostDetails.packageDetails` is empty when `packedShipments` is the only input method. To include parcel comparison data, combine `packedShipments` with `shipments` (inline) or `existingShipmentIds`.
## Example request using `existingShipmentIds` [Skip link to Example request using ,[object Object]](https://docs.shipium.com/docs/ltl-shipment-cost-compare-api\#example-request-using-existingshipmentids)
You can use this scenario when you've already created Shipium shipments and want to retroactively compare what they would have cost as LTL versus parcel.
JSON
```json
{
"shipFromAddress": {
"company": "Harbor Glass Works",
"street1": "4120 Seaport Ave",
"city": "Oakland",
"state": "CA",
"countryCode": "US",
"postalCode": "94607",
"addressType": "commercial"
},
"destinationAddress": {
"company": "Rainier Retail Distribution",
"street1": "8800 Cascade Blvd",
"city": "Kent",
"state": "WA",
"countryCode": "US",
"postalCode": "98032",
"addressType": "commercial"
},
"existingShipmentIds": [\
"7bfef4f3-9e5e-4637-9213-5934f9f104e6",\
"3a2c19d8-2e4b-4891-b1c2-8e3f7d9c5a01"\
],
"ltlShipmentParameters": {
"pickupDate": "2026-04-28",
"pricingTypes": ["contractPallet"],
"accessorialCodes": ["APTD"]
},
"packageShipmentParameters": {
"shipOption": "Standard"
},
"partnerLtlCostId": "harborGlass-compare-2026-04-20-001",
"currencyCode": "usd",
"units": {
"currencyCode": "usd",
"linearUnit": "in",
"weightUnit": "lb"
}
}
```
## Example response using `existingShipmentIds` [Skip link to Example response using ,[object Object]](https://docs.shipium.com/docs/ltl-shipment-cost-compare-api\#example-response-using-existingshipmentids)
This example response shows fields specific to this scenario. The `shipments` example includes the complete response.
JSON
```json
{
"shipiumLtlCostId": "e1a7b265-9d8b-4f5d-de0b-6b0acd7f5c8b",
"partnerLtlCostId": "harborGlass-compare-2026-04-20-001",
"recommendedTransportationType": "ltlTransportation",
"recommendedTransportationTypeCost": 412.85,
"currencyCode": "usd",
"ltlCostDetails": {
"selectedCarrier": {
"carrier": "R+L Carriers",
"carrierServiceMethodId": "rl-standard-ltl",
"totalCost": 412.85,
"estimatedDeliveryDate": "2026-05-01T17:00:00Z",
"serviceLevel": "standard"
},
"totalCost": 412.85
},
"packageCostDetails": {
"totalCost": 487.30,
"packageDetails": [\
{\
"status": "success",\
"shipiumShipmentId": "7bfef4f3-9e5e-4637-9213-5934f9f104e6",\
"carrier": "FedEx",\
"carrierServiceMethodId": "fedex-ground",\
"totalCost": 243.75\
},\
{\
"status": "success",\
"shipiumShipmentId": "3a2c19d8-2e4b-4891-b1c2-8e3f7d9c5a01",\
"carrier": "FedEx",\
"carrierServiceMethodId": "fedex-ground",\
"totalCost": 243.55\
}\
],
"status": "success"
}
}
```
# Retrieve existing LTL and small package shipment cost comparison information [Skip link to Retrieve existing LTL and small package shipment cost comparison information](https://docs.shipium.com/docs/ltl-shipment-cost-compare-api\#retrieve-existing-ltl-and-small-package-shipment-cost-comparison-information)
## Path [Skip link to Path](https://docs.shipium.com/docs/ltl-shipment-cost-compare-api\#path)
**GET**
`https://api.shipium.com/api/v1/ltl/shipment/costCompare/{ltlCostId}`
**Required path element:**`ltlCostId`
## Example cURL call [Skip link to Example cURL call](https://docs.shipium.com/docs/ltl-shipment-cost-compare-api\#example-curl-call-1)
cURL
```curl
curl --request GET
--url https://api.shipium.com/api/v1/ltl/shipment/costCompare/{ltlCostId}
--header 'accept: application/json'
--header $AUTHSTRING
--header 'content-type: application/json'
```
## Example response [Skip link to Example response](https://docs.shipium.com/docs/ltl-shipment-cost-compare-api\#example-response)
JSON
```json
{
"shipiumLtlCostId": "fa2b839c-92e7-48bf-ba09-b0f5a0b0c475",
"partnerLtlCostId": "myCustomPartnerLTLShipmentId123",
"partnerTenantId": "acme-tenant34",
"shipiumTenantId": "469696b8-731e-44bb-82d6-2c437d57f3ce",
"shipFromAddress": {
"name": "Wile E. Coyote",
"phoneNumber": "505-662-7272",
"phoneNumberCountryCode": "+1",
"emailAddress": "wcoyote@acme.com",
"company": "ACME",
"street1": "123 Main St.",
"street2": "Suite 42",
"city": "Albuquerque",
"state": "NM",
"countryCode": "US",
"postalCode": "87121",
"addressType": "commercial"
},
"shipFromTimeZoneId": "mst-gmt-7",
"destinationAddress": {
"name": "Rod Runner",
"company": "ACME",
"addressType": "commercial",
"street1": "43 One Way Lane",
"city": "Seattle",
"state": "WA",
"countryCode": "US",
"postalCode": "14410",
"phoneNumber": "206-123-4567",
"phoneNumberCountryCode": "+1"
},
"destinationTimeZoneId": "cst-gmt-6",
"returnToAddress": {
"name": "Wile E. Coyote",
"phoneNumber": "505-662-7272",
"phoneNumberCountryCode": "+1",
"emailAddress": "wcoyote@acme.com",
"company": "ACME",
"street1": "123 Main St.",
"street2": "Suite 42",
"city": "Albuquerque",
"state": "NM",
"countryCode": "US",
"postalCode": "87121",
"addressType": "commercial"
},
"rawDesiredDeliveryDate": "2024-10-31T10:50:11.123456Z",
"recommendedTransportationType": "ltlTransportation",
"recommendedTransportationTypeCost": 0,
"testMode": true,
"units": {
"currencyCode": "usd",
"linearUnit": "in",
"weightUnit": "lb"
},
"allTransportationTypeCosts": [\
{\
"transportationType": "ltlTransportation",\
"transportationTypeCost": 0\
}\
],
"ltlCostDetails": {
"loadPackaging": [\
{\
"details": {\
"declaredValue": {\
"amount": 12.34,\
"currency": "usd"\
},\
"loadPackagingType": "overboxed",\
"loadPackagingSize": {\
"height": 84,\
"length": 48,\
"linearUnit": "in",\
"weight": 850.25,\
"weightUnit": "lb",\
"width": 40\
},\
"nmfcFreightClass": "50"\
},\
"shipments": [\
{\
"partnerShipmentId": "myCustomPartnerShipmentId123",\
"shipiumShipmentId": "7bfef4f3-9e5e-4637-9213-5934f9f104e6",\
"packageReferenceIdentifier": "1of3"\
}\
]\
}\
],
"evaluatedCarriers": [\
{\
"billableWeight": {\
"weightUnit": "lb",\
"weight": 50\
},\
"billToThirdPartyId": "acme-3rd-party-billing-fedex",\
"carrier": "fedex",\
"carrierAccountId": "acme-fedex-1234",\
"carrierServiceMethodId": "fedex-smartpost-service-method",\
"estimatedDeliveryDate": "2024-10-30T20:47:11.970Z",\
"lineItems": [\
{\
"name": "base",\
"rate": 2.3,\
"carrierSurchargeId": "123451239874980",\
"lineItemType": "surcharge",\
"hiddenFromCarrierCompare": true,\
"hiddenFromInvoice": true,\
"hiddenFromOperational": true,\
"nmfcFreightClass": "50",\
"weight": {\
"weightUnit": "lb",\
"weight": 50\
}\
}\
],\
"loadDeficitCost": {\
"amount": 0,\
"nmfcClass": "50",\
"weight": {\
"weightUnit": "lb",\
"weight": 50\
},\
"rate": 0\
},\
"pickupDateTime": "2024-10-29T20:47:11.970Z",\
"pricingType": "all",\
"quoteId": "e635e871-103c-4a6d-9726-128a3ae51253",\
"quoteEffectiveDateTime": "2024-10-28T20:47:11.970Z",\
"quoteExpirationDateTime": "2024-10-31T20:47:11.970Z",\
"scacCode": "fxsp",\
"serviceLevel": "standard",\
"totalCost": 0\
}\
],
"selectedCarrier": {
"billableWeight": {
"weightUnit": "lb",
"weight": 50
},
"billToThirdPartyId": "acme-3rd-party-billing-ups",
"carrier": "ups",
"carrierAccountId": "ups-1234567",
"carrierServiceMethodId": "ups-ground-service-method",
"estimatedDeliveryDate": "2024-10-30T20:47:11.970Z",
"lineItems": [\
{\
"name": "base",\
"rate": 2.3,\
"carrierSurchargeId": "123451239874980",\
"lineItemType": "surcharge",\
"hiddenFromCarrierCompare": true,\
"hiddenFromInvoice": true,\
"hiddenFromOperational": true,\
"nmfcFreightClass": "50",\
"weight": {\
"weightUnit": "lb",\
"weight": 50\
}\
}\
],
"loadDeficitCost": {
"amount": 0,
"nmfcClass": "50",
"weight": {
"weightUnit": "lb",
"weight": 50
},
"rate": 0
},
"pickupDateTime": "2024-10-29T20:47:11.970Z",
"pricingType": "all",
"quoteId": "20df5261-f0bc-492c-9f31-c580f360b8a7",
"quoteEffectiveDateTime": "2024-10-28T20:47:11.970Z",
"quoteExpirationDateTime": "2024-11-09T20:47:11.970Z",
"scacCode": "UPSN-CG",
"serviceLevel": "standard",
"totalCost": 0
},
"totalCost": 0
},
"ltlShipmentParameters": {
"billToContact": {
"addressType": "commercial",
"city": "Albuquerque",
"company": "ACME",
"countryCode": "US",
"emailAddress": "wcoyote@acme.com",
"name": "Wile E. Coyote",
"phoneNumber": "505-662-7272",
"phoneNumberCountryCode": "+1",
"postalCode": "87121",
"state": "NM",
"street1": "123 Main St.",
"street2": "Suite 42",
"thirdPartyBillingSetId": "acme-3rd-party-billing-set"
},
"carrierServiceMethodAllowList": [\
"ups-ground-service-method",\
"ups-standard-service-method"\
],
"collectOnDelivery": {
"amount": 12.34,
"currency": "usd"
},
"fulfillmentContextIds": [\
"ca037b83-6c47-4515-867e-aa890222c53b"\
],
"fulfillmentType": "customer",
"packagingOptions": [\
{\
"loadPackagingType": "overboxed",\
"loadPackagingSize": {\
"height": 84,\
"length": 48,\
"linearUnit": "in",\
"maximumWeight": 850.25,\
"packagingWeight": 10.125,\
"weightUnit": "lb",\
"width": 40\
}\
}\
],
"paymentDetails": {
"payerType": "consignee",
"paymentTerms": "collect"
},
"pickupDate": "2024-10-31",
"pricingTypes": ["contractPallet"],
"serviceLevels": ["guaranteedMorning"]
},
"packageCostDetails": {
"totalCost": 0,
"packageDetails": [\
{\
"status": "success",\
"statusDetails": "success",\
"carrierSelectionId": "911b488c-c620-4663-a554-bf9628e7ff43",\
"shipiumShipmentId": "7bfef4f3-9e5e-4637-9213-5934f9f104e6",\
"partnerShipmentId": "myCustomPartnerShipmentId123",\
"partnerId": "acme007",\
"carrierAccountId": "acme-ups-01",\
"serviceMethodUrn": "c645ea83-d161-4e28-b8cb-39bf1a620cd3:4e14aaa3-198b-4861-b658-faf51031c84c:83fe5227-a765-45b2-bc2a-cb919ddce922:1",\
"serviceMethodIdentifier": "1f19ca28-9798-42b2-9e8c-f9c3a72c9bab:ZmVkZXgtZXhwcmVzcy1zYXZlci1zZXJ2aWNlLW1ldGhvZDo6OGUzYmIxOGUtMTA3Ni00ODUxLWE4ZTYtZWViZTZmNWUwOTkwOjYyNWRiNjU4LWUwOTEtNGUxYi04ODhhLTMyMTI3MGM4ZTZhZjphOGVjYTRlYS1kMDcwLTRkZWMtOGZiMC0xNGNjMTQxMzJmNWQ6ZmVkZXg6NWExZWE3MjgtNGJhMi00Y2M2LTg5MmMtMWYxMjJmMzUwNzc1Ojo",\
"carrier": "ups",\
"carrierServiceMethodId": "ups-ground-service-method",\
"serviceMethodName": "ground",\
"costAdjustConfigId": "331de530-6a92-4238-9d3c-70083b19d94e",\
"totalCost": 0,\
"carrierCompareCost": 0,\
"carrierInvoiceCost": 0,\
"operationalCost": 2.7,\
"thirdPartyBilling": true,\
"carrierSelectionDateTime": "2024-10-27T20:47:11.970Z",\
"carrierZoneId": "ups-zone-7",\
"calculatedBillableWeight": {\
"weightUnit": "lb",\
"weight": 50\
},\
"laneMatch": {\
"laneId": "asdqwdq-qwd123ds-123asdwd-123asd",\
"partnerLaneId": "custom partner provided id"\
},\
"evaluatedServiceMethods": [\
{\
"carrier": "ups",\
"carrierServiceMethodId": "ups-ground-service-method",\
"serviceMethodName": "ground",\
"carrierAccountId": "acme-ups-01",\
"totalCost": 0,\
"estimatedDeliveryDate": "2024-10-30T20:47:11.970Z",\
"rateCurrency": "usd",\
"lineItems": [\
{\
"name": "base",\
"rate": 2.3,\
"carrierSurchargeId": "123451239874980",\
"lineItemType": "surcharge",\
"hiddenFromCarrierCompare": true,\
"hiddenFromInvoice": true,\
"hiddenFromOperational": true\
}\
]\
}\
],\
"cancellationDateTime": "2024-10-31T10:50:11.123456Z",\
"effectiveShipDateTime": "2024-10-30T20:47:11.970Z"\
}\
],
"status": "success"
},
"packageShipmentParameters": {
"carrierServiceMethodAllowList": [\
"ups-ground-service-method",\
"ups-standard-service-method"\
],
"deliverySignatureOption": "resident_signature",
"deliveryWindow": "string",
"forceThirdPartyBilling": false,
"fulfillmentContextIds": [\
"ca037b83-6c47-4515-867e-aa890222c53b"\
],
"fulfillmentType": "customer",
"ignoreCarrierMinimumDimensions": false,
"ignoreUpgradeSpendLimits": false,
"includeInjectionProfiles": false,
"lastMileDeliveryOptions": {
"deliveryInstruction": "LEAVE_AT_DOOR",
"undeliverableInstruction": "LEAVE_AT_DOOR",
"tip": {
"type": "FIXED",
"value": 0,
"currency": "usd"
},
"tipForLabelCreate": {
"type": "FIXED",
"value": 0,
"currency": "usd"
},
"deliverableActionForLabelCreate": "RETURN",
"undeliverableActionForLabelCreate": "RETURN"
},
"pickupWindow": "string",
"preferredCarrierDeliveryDateTime": "2019-10-31T20:00:00Z",
"saturdayDelivery": false,
"serviceMethodPoBoxAllowList": [\
"string"\
],
"shipOption": "Standard",
"thirdPartyBillingSetId": "acme-3rd-party-billing-set"
},
"packedShipments": [\
{\
"declaredValue": {\
"amount": 12.34,\
"currency": "usd"\
},\
"loadPackagingType": "overboxed",\
"loadPackagingSize": {\
"height": 84,\
"length": 48,\
"linearUnit": "in",\
"weight": 850.25,\
"weightUnit": "lb",\
"width": 40\
},\
"nmfcFreightClass": "50"\
}\
],
"shipments": [\
{\
"partnerShipmentId": "myCustomPartnerShipmentId123",\
"shipiumShipmentId": "7bfef4f3-9e5e-4637-9213-5934f9f104e6"\
}\
]
}
```
# Resources [Skip link to Resources](https://docs.shipium.com/docs/ltl-shipment-cost-compare-api\#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)
Updated 24 days ago
* * *
Did this page help you?
Yes
No
Copy Page
🦉
# Recipe Title
Recipe Description
x
```
```
1{"success":true}
## Are you sure?