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

🔐
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.

👍
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

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 instead.

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

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

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.

Top-level request fields

Required fields

Field	Details
`currencyCode`	Type: String Example: `usd` Description: The 3-character ISO 4217 currency code in which all the rates for shipping will be calculated and returned

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

Field	Details
`businessDaysOfTransit`	Type: Integer (int32) Example: `3` Description: Indicates the number of business days 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 date or a local date for desired delivery: `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 that made it through filtering.
`includeLineItemsInEvaluatedServiceMethods`	Type: Boolean Values: `true` or `false` Description: When `true`, a response will include line item information 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 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 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 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, and label generation will generate a test label.

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.

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. 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 (DDD) if the lowest cost carrier service method is unable to safely meet the DDD.
`desiredDeliveryDateOptions.currencyCode`	Type: String Description: The ISO 4217 currency code of the `upgradeCostDeltaMax`

destinationAddress fields

Required fields

Field	Details
`destinationAddress.countryCode`	Type: String Description: The ISO 3166-1 country code 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

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

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

Required fields

Field	Details
`shipFromAddress.countryCode`	Type: String Description: The ISO 3166-1 country code 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

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

Conditional fields

Field	Details
`returnToAddress.countryCode`	Type: String Condition: Required if including `returnToAddress` Description: The ISO 3166-1 country code 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

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

All fields in this object are required.

Field	Details
`units.currencyCode`	Type: String Example: `usd` Description: The ISO-4217 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

Required fields

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

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 and a list of `carrierServiceMethodIds` in Supported Carriers.
`ltlShipmentParameters.fulfillmentContextIds`	Type: String Description: A collection of fulfillment context 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 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 . Description: Any optional requested accessorial services will be passed to the carrier.

ltlShipmentParameters.billToContact fields

The bill-to-contact fields refer to the entity that should be billed for the LTL shipment; by default, the carrier contracts in the fulfillment context will be used for billing. Either the addressLineComponents or the other address fields should be provided.

Required fields

Field	Details
`ltlShipmentParameters.billToContact.countryCode`	Type: String Description: The ISO 3166-1 country code 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 set ID; this value is used to look up the account number each LTL carrier uses to determine pricing agreement.

Optional fields

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

Conditional fields

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 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

Conditional fields

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

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

Conditional fields

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

Required fields

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

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 currency code of the amount of money that should be paid by the recipient upon delivery of the package

Optional fields

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

Optional fields

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 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 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

Required fields

Field	Details
`shipments.packages.packageReferenceIdentifier`	Type: String Description: Used to correlate packages to label documents from the carrier

Optional fields

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 timestamp for when the package was delivered to the customer

shipments.packages.orderItemQuantities fields

Required fields

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

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 and shipments containing hazardous materials Description: A list of product properties that affect carrier selection and handling; see productDetails Reference for details.

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 and shipments containing hazardous materials
Description: A list of product properties that affect carrier selection and handling; see productDetails Reference for details.

Optional fields

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 (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

For information on shipping hazmat items, see Hazardous Materials.

Conditional fields

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

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

Conditional fields

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

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

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

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 currency code for the declared value

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 and a list of `carrierServiceMethodIds` in Supported Carriers.
`packageShipmentParameters .deliverySignatureOption`	Type: String (enumeration) Values: `AdultResidentSignature`, `AdultSignature`, `None`, `ResidentSignature`, `Signature`, `Unknown` Description: A delivery signature option 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 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 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 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. 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 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 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.
`packageShipmentParameters.shipOption`	Type: String Example: `standard` Description: A high-level shipping option 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 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

Conditional fields

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 profile that should be considered during carrier selection

Optional fields

Field	Details
`packageShipmentParameters.injectionParameters .injectionSiteId`	Type: String Description: The Shipium ID or your organization's unique ID for an injection site that should be considered during carrier selection; if an `injectionSiteId` is specified, it must be accompanied by an `injectionProfileId`.

packageShipmentParameters.lastMileDeliveryOptions 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

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

curl --request POST   
  --url <<api_url>>/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`

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.

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

In this example, parcel shipping is more economical for this shipment. For multi-pallet loads, LTL typically becomes the more cost-effective choice.

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

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.

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

This example response shows fields specific to this scenario. The shipments example includes the complete response.

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

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.

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

This example response shows fields specific to this scenario. The shipments example includes the complete response.

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

Path

GET

https://api.shipium.com/api/v1/ltl/shipment/costCompare/{ltlCostId}

Required path element: ltlCostId

Example cURL call

curl --request GET   
  --url <<api_url>>/api/v1/ltl/shipment/costCompare/{ltlCostId} 
  --header 'accept: application/json' 
  --header $AUTHSTRING  
  --header 'content-type: application/json'

Example response

{
  "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": "[email protected]",
    "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": "[email protected]",
    "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": "[email protected]",
      "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

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

Get started

Authentication for API Calls

Test mode

When to use the LTL Shipment Cost Compare endpoint

Compare LTL and small package shipping costs

Choose an input method

Request and response fields for API calls

Top-level request fields

Required fields

Conditional fields

Optional fields

desiredDeliveryDateOptions fields

destinationAddress fields

Required fields

Conditional fields

Optional fields

shipFromAddress fields

Required fields

Optional fields

returnToAddress fields

Conditional fields

Optional fields

units fields

ltlShipmentParameters fields

Required fields

Optional fields

ltlShipmentParameters.billToContact fields

Required fields

Optional fields

ltlShipmentParameters.collectOnDelivery fields

Conditional fields

ltlShipmentParameters.hazmatContact fields

Conditional fields

Optional fields

ltlShipmentParameters.packagingOptions fields

Conditional fields

packedShipments fields

Required fields

Conditional fields

Optional fields

shipments fields

Optional fields

shipments.packages fields

Required fields

Optional fields

shipments.packages.orderItemQuantities fields

Required fields

Conditional fields

Optional fields

shipments.packages.orderItemQuantities.hazmatInfo fields

Conditional fields

Optional fields

shipments.packages.packagingType fields

Conditional fields

Optional fields

shipments.packages.totalWeight fields

shipments.packages.totalDeclaredValue fields

packageShipmentParameters fields

packageShipmentParameters.injectionParameters fields

Conditional fields

Optional fields

packageShipmentParameters.lastMileDeliveryOptions fields

Response attributes

Example cURL call

Example request using shipments

Example response using shipments

Example request using packedShipments

Example response using packedShipments

Example request using existingShipmentIds

Example response using existingShipmentIds

Retrieve existing LTL and small package shipment cost comparison information

Path

Example cURL call

Example response

Resources

Example request using `shipments`

Example response using `shipments`

Example request using `packedShipments`

Example response using `packedShipments`

Example request using `existingShipmentIds`

Example response using `existingShipmentIds`