API Reference | ReDoc

Landed Cost

The Landed Cost Quote API allows you to estimate the all-inclusive cost of international shipments - including applicable duties, VAT, taxes, brokerage fees, and other fees. Required parameters include the currency and shipment details, such as the commodity ID, price, quantity, and country code of origin.

Key Business Values:

  • Enhanced Customer Experience: Get a quick and accurate quote on the landed cost of a shipment, including the cost of goods, transportation, and any other fees associated with getting the goods to their destination.
  • Operational Efficiency: Simplify the process of calculating landed costs by eliminating the need to manually research and calculate all of the different fees involved.
  • Data-Driven Decision Making: Improve decision-making by having a clear understanding of the total cost of shipping goods before you commit to a purchase..
  • Optimizing Cash Flow: Streamline your shipping process by integrating the Landed Cost Quote API into your existing systems.

Reference


Try out UPS APIs with example requests using Postman. Explore API documentation and sample applications through GitHub.

Run In Postman Open in GitHub

Landed Cost Quote API

The Landed Cost Quote API allows you to estimate the all-inclusive cost of international shipments - including applicable duties, VAT, taxes, brokerage fees, and other fees. Required parameters include the currency and shipment details, such as the commodity ID, price, quantity, and country code of origin.

SecurityOAuth2
Request
path Parameters
version
required
string
Default: "v1"

Version of the API.

header Parameters
transId
required
string

An identifier unique to the request. Length: 32

transactionSrc
required
string
Default: testing

An identifier of the client/source application that is making the request. Length: 512

AccountNumber
string

The UPS account number.

Request Body schema: application/json

Generate sample code for popular API requests by selecting an example below. To view a full sample request and response, first click "Authorize" and enter your application credentials, then populate the required parameters above and click "Try it out".

<= 1
currencyCode
required
string <= 3 characters <= 1

Specifies the currency of transaction or purchase.

transID
required
string <= 50 characters <= 1

Unique transaction ID for the request.

allowPartialLandedCostResult
boolean <= 1

An optional flag to indicate that partial landed cost calculations are acceptable to be used by upstream systems. When set to false, the system will return an error when at least one commodity in the shipment is invalid (all or none), and no results will be sent back for that request. When set to true, the system will return partial calculations when applicable.

Valid values: true = Partial Landed Cost result will return. false = All or No result will return (default).

alversion
required
integer <= 1

Version number of the instance that processed this request. This must match the major number of the corresponding ICD version.

required
object (LandedCostRequest_Shipment) <= 1

Every Landed Cost request must be based on a shipment.

id
required
string <= 100 characters <= 1

Specifies the Shipment ID in the Landed Cost quote. It is an arbitrary string provided by the user of the API and will be returned with the Landed Cost Quote to indicate which shipment the tariffs apply to. There are similar IDs associated with the Product and Order objects.

importCountryCode
required
string <= 2 characters <= 1

Specifies the Import/Ship-To/Destination/Final country of the shipment. Please check country list in the Appendix.

importProvince
string <= 100 characters <= 1

Province/State is supported only for a few countries such as Mexico, Canada, etc. Please check Province list in the Appendix

shipDate
string <= 10 characters <= 1

Defaults to current date if not provided. Date format: YYYY-MM-DD.

incoterms
string <= 3 characters <= 1
Default: "FOB"

Supported Incoterm Values:

  1. CFR - Cost & Freight
  2. CIF - Cost, Insurance & Freight
  3. CIP - Carriage and Insurance Paid-To
  4. CPT - Carriage Paid-To
  5. DAP - Delivered At Place
  6. DAT - Delivered At Terminal
  7. DDP - Delivered Duty Paid
  8. DPU - Delivered at Place Unloaded
  9. EXW - Ex Works
  10. FAS - Free Alongside Ship
  11. FCA - Free Carrier
  12. FOB - Free On Board (Default)
exportCountryCode
required
string <= 2 characters <= 1

Specifies the export/ship-from/origin country of the shipment. Please check country List in the Appendix section.

Note: Export country code must be different from the import country code.

transModes
string <= 9 characters <= 1

The modes of transportation (in upper case). Supported Values:

  1. INT_AIR 2. INT_OCEAN
  2. INT_RAIL
  3. INT_TRUCK
  4. DOM_AIR
  5. DOM_OCEAN
  6. DOM_RAIL
  7. DOM_TRUCK

Default value will vary based on the import country.

transportCost
number <= 1

Specifies the Freight charge or transport costs, which are used for tariff calculations. Landed cost result might have some dependency on the freight charges in some countries. Therefore, freight amount should be always provided for accurate Landed Cost result.

Allowed values:

  1. Any non-negative floating-point number.
  2. Numeric value with optional decimal value.
shipmentType
string <= 35 characters <= 1

Specifies the shipment type such as Gift, Document, Commercial (Sale), etc.

Supported Shipment Types:

  1. GIFT
  2. COMMERCIAL
  3. SALE
  4. SAMPLE
  5. REPAIR
  6. RETURN
  7. OTHER

Default value will vary and based on import country.

required
Array of objects (Request_ShipmentItems) <= 99

Array of shipment item objects (commodities), that are in a shipment.

Array
commodityId
required
string <= 100 characters <= 1

Commodity ID is used to associate tariffs with product in the output. Should be unique for each commodity in a request. It is an arbitrary string provided by the user of the API that will be returned with the Landed Cost Quote to indicate which commodity the tariffs apply to.

grossWeight
number <= 1

Specifies the gross weight of the commodity as any non-negative value.

grossWeightUnit
string <= 2 characters <= 1

Specifies the units of the gross weight. Required if GrossWeight is used. If GrossWeight is not specified, this value must not be set to anything but null. Supported values: LB, KG

priceEach
required
number <= 1

Specifies the price for each commodity unit in the settlement currency. The total price of the entire number of shipmentItems may not exceed 999999999999.99

commodityCurrencyCode
required
string <= 3 characters <= 1

Specifies the Currency Code used for commodity price. All commodities must have the same currency code.

quantity
required
integer <= 1

Specifies the number of product units to be shipped. The total price of the entire number of shipmentItems may not exceed 999999999999.99, 1 or greater than 1

UOM
required
string <= 1

Specifies unit of measure. Check UOM List in the Appendices section.

hsCode
string <= 40 characters <= 1

Specifies a valid HS or HTS code for the shipment's destination or import country. This field is required if description is not provided.

description
string <= 150 characters <= 1

This field is populated with description of the commodity. This field is required if hsCode is not provided.

originCountryCode
required
string <= 2 characters <= 1

Country of Manufacture or origin.

Responses
200

successful operation

400

Invalid Request

401

Unauthorized Request

403

Blocked Merchant

429

Rate Limit Exceeded

post/landedcost/{version}/quotes
Request samples
application/json
{
  • "currencyCode": "GBP",
  • "transID": "325467165",
  • "allowPartialLandedCostResult": false,
  • "shipment": {
    }
}
Response samples
application/json
{
  • "shipment": {
    },
  • "alversion": 0,
  • "dpversion": null,
  • "transID": "325467165",
  • "error": null,
  • "perfStats": {
    }
}
➔ Next to Locator