Endpoint

Calculate landed cost

Runs the landed-cost engine for one shipment. Resolves MFN, Section 232 / 301 / 122 / 338, AD/CVD, FTA preferences, VAT/GST, MPF, HMF, and de-minimis in a single call.

POST/v1/calc

Request body

destination_country

string (ISO-2)Required

Destination country. Use EU with eu_member_state for European Union imports.

Example: US

origin_country

string (ISO-2)Required

Country of origin at the shipment level. Line-level origin_country overrides for that line.

Example: CN

incoterm

enumRequired

EXW, FCA, CPT, CIP, DAP, DPU, DDP, FAS, FOB, CFR, CIF.

Example: FOB

transport_mode

enumRequired

ocean, air, truck, rail, express.

Example: ocean

currency

string (ISO-4217)Required

Invoice currency. Auto-converted to the customs currency via CBP weekly rate (US) or ECB spot fallback.

Example: USD

line_items

LineItem[]Required

One or more line items. See the LineItem schema below.

freight

number

Shipment-level freight in the invoice currency. Prorated across lines by value.

Example: 250

insurance

number

Shipment-level insurance in the invoice currency.

Example: 45

other_dutiable_charges

number

Legacy field for miscellaneous dutiable additions. Prefer customs_value_adjustments.

customs_value_adjustments

object

Itemized 19 CFR 152.103 additions (assists, royalties, packing) and deductions (prompt_payment_discount, buying_commission).

eu_member_state

string (ISO-2)

Required when destination_country is EU. Drives the correct VAT rate.

Example: DE

br_state

string

Two-letter Brazilian state for ICMS calculation.

Example: SP

ca_province

string

Two-letter Canadian province for PST/HST combined rate.

Example: ON

usmca_qualifying

boolean

Set true to claim USMCA preferential treatment (US, CA, MX only).

fta_id

string

FTA program ID (KORUS, CAFTA_DR, etc.) for non-USMCA preferential claims.

calculation_date

date

ISO date the calculation is effective. Defaults to today.

export_date

date

ISO date the shipment left the country of exportation. Drives 19 CFR 141.62 FX lookup.

input_method

enum

upload or manual. Persisted with the calculation for audit trail.

LineItem schema

description

stringRequired

Free-text product description. Passed to the classifier when hs_code is missing.

hs_code

string

HS or HTS code (4 to 13 digits, dots optional). Empty triggers inline classification.

Example: 8517.62.00

quantity

numberRequired

Positive number of units.

unit_value

numberRequired

Per-unit invoice value in the shipment currency.

origin_country

string (ISO-2)Required

Per-line origin country.

weight_kg

number

Per-unit weight in kilograms. Used for weight-based fees (Air, Section 232 aluminum overrides).

smelter_country

string (ISO-2)

Chapter 76 aluminum smelter country. RU triggers the 200% Russia-aluminum override.

preference_program

string

Per-line FTA program claim, e.g. KORUS, S, P+, USMCA.

Response 200

id

uuid

Persisted calculation row ID. Null in sandbox mode.

shipment_id

uuid

Auto-detected shipment ID when the invoice extractor found a container / BoL / AWB. Null otherwise.

result

CalcResult

goods_value, freight, insurance, customs_value, duty_amount, taxes_amount, fees_amount, total_landed_cost, currency, calculation_date, breakdown[], de_minimis, warnings[].

compliance_flags

ComplianceFlag[]

PGA, restricted product, denied party, unit-price deviation, data-freshness, Section 122 sunset banner.

fta_opportunities

ComplianceFlag[]

Subset of compliance_flags with kind = fta_opportunity or fta_qualified.

data_as_of

object

Per-source last_succeeded_at ISO timestamps for the volatile feeds (FX, sanctions, US overlays).

data_stale

boolean

True when any volatile source is over 24 hours old.

Example request

curl https://www.landedfees.com/api/v1/calc \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
  "destination_country": "US",
  "origin_country": "CN",
  "incoterm": "FOB",
  "transport_mode": "ocean",
  "currency": "USD",
  "freight": 250,
  "insurance": 45,
  "line_items": [
    {
      "description": "Wireless earbuds, plastic housing",
      "hs_code": "8517.62.00",
      "quantity": 500,
      "unit_value": 12.50,
      "origin_country": "CN",
      "weight_kg": 0.15
    }
  ]
}'

Endpoint

Calculate landed cost

Runs the landed-cost engine for one shipment. Resolves MFN, Section 232 / 301 / 122 / 338, AD/CVD, FTA preferences, VAT/GST, MPF, HMF, and de-minimis in a single call.

POST/v1/calc

Request body

destination_country

string (ISO-2)Required

Destination country. Use EU with eu_member_state for European Union imports.

Example: US

origin_country

string (ISO-2)Required

Country of origin at the shipment level. Line-level origin_country overrides for that line.

Example: CN

incoterm

enumRequired

EXW, FCA, CPT, CIP, DAP, DPU, DDP, FAS, FOB, CFR, CIF.

Example: FOB

transport_mode

enumRequired

ocean, air, truck, rail, express.

Example: ocean

currency

string (ISO-4217)Required

Invoice currency. Auto-converted to the customs currency via CBP weekly rate (US) or ECB spot fallback.

Example: USD

line_items

LineItem[]Required

One or more line items. See the LineItem schema below.

freight

number

Shipment-level freight in the invoice currency. Prorated across lines by value.

Example: 250

insurance

number

Shipment-level insurance in the invoice currency.

Example: 45

other_dutiable_charges

number

Legacy field for miscellaneous dutiable additions. Prefer customs_value_adjustments.

customs_value_adjustments

object

Itemized 19 CFR 152.103 additions (assists, royalties, packing) and deductions (prompt_payment_discount, buying_commission).

eu_member_state

string (ISO-2)

Required when destination_country is EU. Drives the correct VAT rate.

Example: DE

br_state

string

Two-letter Brazilian state for ICMS calculation.

Example: SP

ca_province

string

Two-letter Canadian province for PST/HST combined rate.

Example: ON

usmca_qualifying

boolean

Set true to claim USMCA preferential treatment (US, CA, MX only).

fta_id

string

FTA program ID (KORUS, CAFTA_DR, etc.) for non-USMCA preferential claims.

calculation_date

date

ISO date the calculation is effective. Defaults to today.

export_date

date

ISO date the shipment left the country of exportation. Drives 19 CFR 141.62 FX lookup.

input_method

enum

upload or manual. Persisted with the calculation for audit trail.

LineItem schema

description

stringRequired

Free-text product description. Passed to the classifier when hs_code is missing.

hs_code

string

HS or HTS code (4 to 13 digits, dots optional). Empty triggers inline classification.

Example: 8517.62.00

quantity

numberRequired

Positive number of units.

unit_value

numberRequired

Per-unit invoice value in the shipment currency.

origin_country

string (ISO-2)Required

Per-line origin country.

weight_kg

number

Per-unit weight in kilograms. Used for weight-based fees (Air, Section 232 aluminum overrides).

smelter_country

string (ISO-2)

Chapter 76 aluminum smelter country. RU triggers the 200% Russia-aluminum override.

preference_program

string

Per-line FTA program claim, e.g. KORUS, S, P+, USMCA.

Response 200

id

uuid

Persisted calculation row ID. Null in sandbox mode.

shipment_id

uuid

Auto-detected shipment ID when the invoice extractor found a container / BoL / AWB. Null otherwise.

result

CalcResult

goods_value, freight, insurance, customs_value, duty_amount, taxes_amount, fees_amount, total_landed_cost, currency, calculation_date, breakdown[], de_minimis, warnings[].

compliance_flags

ComplianceFlag[]

PGA, restricted product, denied party, unit-price deviation, data-freshness, Section 122 sunset banner.

fta_opportunities

ComplianceFlag[]

Subset of compliance_flags with kind = fta_opportunity or fta_qualified.

data_as_of

object

Per-source last_succeeded_at ISO timestamps for the volatile feeds (FX, sanctions, US overlays).

data_stale

boolean

True when any volatile source is over 24 hours old.

Example request

curl https://www.landedfees.com/api/v1/calc \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
  "destination_country": "US",
  "origin_country": "CN",
  "incoterm": "FOB",
  "transport_mode": "ocean",
  "currency": "USD",
  "freight": 250,
  "insurance": 45,
  "line_items": [
    {
      "description": "Wireless earbuds, plastic housing",
      "hs_code": "8517.62.00",
      "quantity": 500,
      "unit_value": 12.50,
      "origin_country": "CN",
      "weight_kg": 0.15
    }
  ]
}'