Endpoint

Compare origins

Runs the landed-cost engine in parallel across 1 to 6 origin countries for the same HS + destination + value + freight. Per-origin failures do not fail the batch: rows without verified coverage return coverage=false with a message so the UI can render them honestly.

POST/v1/compare

Request body

hs_code

string (6+ digits)Required

HS or HTS code (dots allowed). Same code applied to every origin.

destination

string (ISO-2)Required

Destination country.

value

numberRequired

Total goods value in the shipment currency.

currency

string (ISO-4217)

Defaults to USD.

freight

number

Shipment-level freight. Applied identically to every origin so the deltas reflect duty only.

insurance

number

Shipment-level insurance.

incoterm

enum

Defaults to FOB.

transport_mode

enum

Defaults to ocean.

origins

string[] (ISO-2)Required

1 to 6 origin countries. Duplicates are collapsed silently.

eu_member_state

string (ISO-2)

Required when destination is EU.

br_state

string

Brazilian state.

ca_province

string

Canadian province.

calculation_date

date

ISO date the comparison is effective on.

Response 200

hs_code

string

Echoed from the request.

destination

string

Echoed.

value

number

Echoed.

results

OriginResult[]

One row per origin. Covered rows first (sorted cheapest to most expensive), uncovered rows appended.

results[].origin

string

ISO-2 origin.

results[].coverage

boolean

True when LandedFees returned a verified stack. False otherwise (see coverage_message).

results[].total_landed_cost

number

Total landed cost including duty, taxes, fees, freight, insurance.

results[].breakdown_summary

object

Per-code totals: MFN, SEC_122, SEC_301, SEC_301_FL, SEC_338_CA, SEC_232, SEC_232_PHARMA, AD_CVD, MPF, HMF, VAT, GST, GST_HST, IGST, BCD, II, IPI, ICMS.

results[].flags

object

denied_party, pga, restriction, ad_cvd, fta_opportunity booleans.

results[].delta_vs_cheapest

number

Difference from the cheapest covered row.

results[].delta_pct

number

Percentage delta from the cheapest covered row.

calculated_at

date-time

ISO timestamp the comparison was computed.

Example request

curl https://www.landedfees.com/api/v1/compare \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
  "hs_code": "8518.30.20",
  "destination": "US",
  "value": 64250,
  "currency": "USD",
  "freight": 3200,
  "insurance": 480,
  "incoterm": "FOB",
  "transport_mode": "ocean",
  "origins": ["CN", "VN", "MX", "IN"]
}'

Endpoint

Compare origins

POST/v1/compare

Request body

hs_code

string (6+ digits)Required

HS or HTS code (dots allowed). Same code applied to every origin.

destination

string (ISO-2)Required

Destination country.

value

numberRequired

Total goods value in the shipment currency.

currency

string (ISO-4217)

Defaults to USD.

freight

number

Shipment-level freight. Applied identically to every origin so the deltas reflect duty only.

insurance

number

Shipment-level insurance.

incoterm

enum

Defaults to FOB.

transport_mode

enum

Defaults to ocean.

origins

string[] (ISO-2)Required

1 to 6 origin countries. Duplicates are collapsed silently.

eu_member_state

string (ISO-2)

Required when destination is EU.

br_state

string

Brazilian state.

ca_province

string

Canadian province.

calculation_date

date

ISO date the comparison is effective on.

Response 200

hs_code

string

Echoed from the request.

destination

string

Echoed.

value

number

Echoed.

results

OriginResult[]

One row per origin. Covered rows first (sorted cheapest to most expensive), uncovered rows appended.

results[].origin

string

ISO-2 origin.

results[].coverage

boolean

True when LandedFees returned a verified stack. False otherwise (see coverage_message).

results[].total_landed_cost

number

Total landed cost including duty, taxes, fees, freight, insurance.

results[].breakdown_summary

object

Per-code totals: MFN, SEC_122, SEC_301, SEC_301_FL, SEC_338_CA, SEC_232, SEC_232_PHARMA, AD_CVD, MPF, HMF, VAT, GST, GST_HST, IGST, BCD, II, IPI, ICMS.

results[].flags

object

denied_party, pga, restriction, ad_cvd, fta_opportunity booleans.

results[].delta_vs_cheapest

number

Difference from the cheapest covered row.

results[].delta_pct

number

Percentage delta from the cheapest covered row.

calculated_at

date-time

ISO timestamp the comparison was computed.

Example request

curl https://www.landedfees.com/api/v1/compare \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
  "hs_code": "8518.30.20",
  "destination": "US",
  "value": 64250,
  "currency": "USD",
  "freight": 3200,
  "insurance": 480,
  "incoterm": "FOB",
  "transport_mode": "ocean",
  "origins": ["CN", "VN", "MX", "IN"]
}'