> ## Documentation Index > Fetch the complete documentation index at: https://docs.landedfees.com/llms.txt > Use this file to discover all available pages before exploring further. # Calculate landed cost > Runs the landed-cost engine end-to-end for a single shipment. Resolves MFN, Section 232 / 301 / 122 / 338, AD/CVD, FTA preferences, VAT/GST, MPF, HMF, and de-minimis. Returns a full CalculationResult plus compliance flags (PGA, restricted product, denied party, unit-price deviation, data-freshness, Section 122 sunset banner). ## OpenAPI ````yaml POST /v1/calc openapi: 3.1.0 info: title: LandedFees API version: 1.0.0 summary: Landed-cost, HS classification, and origin-comparison API. description: | LandedFees exposes five stable v1 endpoints for landed-cost calculation, HS classification, multi-origin comparison, and rate lookup. All requests require a bearer API key (format `sk_live_...`). Every response returns JSON. Rate limits are surfaced via `X-RateLimit-*` headers. Data provenance: rates resolve against the same live tables the LandedFees UI uses (USITC HTS, EU TARIC, HMRC UK Trade Tariff, WCO HS, CBP weekly FX per 19 CFR 141.62). No estimates. Idempotency: mutation-like endpoints (calc, calc/bulk, classify, compare) accept an `Idempotency-Key` header. Repeating the same key within 24 hours returns the cached response. contact: name: LandedFees Support url: https://www.landedfees.com/support email: support@landedfees.com license: name: Proprietary url: https://www.landedfees.com/terms servers: - url: https://www.landedfees.com description: Production (v1) security: - bearerAuth: [] tags: - name: Calculate description: Landed-cost calculation for single and bulk shipments. - name: Classify description: HS / HTS code classification from a product description. - name: Compare description: Side-by-side landed-cost comparison across origins. - name: Rates description: Duty and tax rate lookup by country and HS code. paths: /v1/calc: post: tags: - Calculate summary: Calculate landed cost for one shipment. description: | Runs the landed-cost engine end-to-end for a single shipment. Resolves MFN, Section 232 / 301 / 122 / 338, AD/CVD, FTA preferences, VAT/GST, MPF, HMF, and de-minimis. Returns a full CalculationResult plus compliance flags (PGA, restricted product, denied party, unit-price deviation, data-freshness, Section 122 sunset banner). operationId: calc parameters: - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CalcRequest' examples: earbuds_cn_to_us: summary: Wireless earbuds CN to US, single line value: 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.5 origin_country: CN weight_kg: 0.15 responses: '200': description: Calculation completed. headers: X-RateLimit-Limit: $ref: '#/components/headers/XRateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/XRateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/XRateLimitReset' content: application/json: schema: $ref: '#/components/schemas/CalcResponse' examples: ok: summary: Success value: id: 5f6b7c8d-1234-4abc-9def-0123456789ab result: goods_value: 6250 freight: 250 insurance: 45 customs_value: 6545 duty_amount: 3796.1 taxes_amount: 0 fees_amount: 25.67 total_landed_cost: 10366.77 currency: USD calculation_date: '2026-08-23' breakdown: - code: MFN amount: 0 rate: 0 exempted: false - code: SEC_301 amount: 1636.25 rate: 0.25 exempted: false - code: SEC_232 amount: 0 rate: 0 exempted: false compliance_flags: [] data_stale: false '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '402': $ref: '#/components/responses/PaymentRequired' '422': $ref: '#/components/responses/UnprocessableEntity' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalError' components: parameters: IdempotencyKey: name: Idempotency-Key in: header required: false description: | Client-generated unique string (recommended UUID v4). Repeating the same key within 24 hours returns the cached response for the original request body. Different bodies with the same key return HTTP 409. schema: type: string minLength: 8 maxLength: 128 example: e4c1d2a0-8f6b-4c9d-a123-2f8b7c5e9d10 schemas: CalcRequest: type: object required: - destination_country - origin_country - incoterm - transport_mode - currency - line_items properties: destination_country: type: string minLength: 2 maxLength: 2 example: US origin_country: type: string minLength: 2 maxLength: 2 example: CN incoterm: $ref: '#/components/schemas/Incoterm' transport_mode: $ref: '#/components/schemas/TransportMode' currency: type: string minLength: 3 maxLength: 3 example: USD line_items: type: array minItems: 1 items: $ref: '#/components/schemas/LineItem' freight: type: number minimum: 0 default: 0 insurance: type: number minimum: 0 default: 0 other_dutiable_charges: type: number minimum: 0 default: 0 customs_value_adjustments: $ref: '#/components/schemas/CustomsValueAdjustments' eu_member_state: type: string minLength: 2 maxLength: 2 description: Required when destination_country is EU. br_state: type: string minLength: 2 maxLength: 2 ca_province: type: string minLength: 2 maxLength: 2 usmca_qualifying: type: boolean fta_id: type: string description: FTA program ID (KORUS, CAFTA_DR, etc.). calculation_date: type: string format: date export_date: type: string format: date description: | ISO date the shipment left the country of exportation. Drives the CBP-published weekly FX lookup per 19 CFR 141.62. Falls back to calculation_date when unset. input_method: type: string enum: - upload - manual default: manual extracted_data: nullable: true description: Snapshot of extractor output for auto-detected fields. invoice_file_url: type: string nullable: true CalcResponse: type: object properties: id: type: string format: uuid nullable: true shipment_id: type: string format: uuid nullable: true result: $ref: '#/components/schemas/CalcResult' compliance_flags: type: array items: $ref: '#/components/schemas/ComplianceFlag' fta_opportunities: type: array items: $ref: '#/components/schemas/ComplianceFlag' data_as_of: type: object additionalProperties: type: string format: date-time data_stale: type: boolean Incoterm: type: string enum: - EXW - FCA - CPT - CIP - DAP - DPU - DDP - FAS - FOB - CFR - CIF TransportMode: type: string enum: - ocean - air - truck - rail - express LineItem: type: object required: - description - quantity - unit_value - origin_country properties: description: type: string minLength: 1 hs_code: type: string description: >- HS / HTS code, 4 to 13 digits (dots allowed). Empty string triggers inline classification. example: 8517.62.00 quantity: type: number exclusiveMinimum: 0 unit_value: type: number minimum: 0 origin_country: type: string minLength: 2 maxLength: 2 example: CN weight_kg: type: number minimum: 0 nullable: true manufacturer: type: string nullable: true notes: type: string nullable: true smelter_country: type: string minLength: 2 maxLength: 2 nullable: true description: | ISO-2 smelter country for Chapter 76 aluminum (or Chapters 72/73/74 metals). Triggers Section 232 Russia-aluminum 200 percent override when set to RU regardless of origin_country. preference_program: type: string nullable: true description: | Per-line preference program claim (USMCA, KORUS, CAFTA-DR, S, S+, P, P+, bilateral ISO-2s, etc.). CustomsValueAdjustments: type: object description: Itemized customs-value adjustments per 19 CFR 152.103. properties: assists: type: number minimum: 0 royalties_license_fees: type: number minimum: 0 selling_commission: type: number minimum: 0 packing_costs: type: number minimum: 0 proceeds_subsequent_resale: type: number minimum: 0 buying_commission: type: number minimum: 0 prompt_payment_discount: type: number minimum: 0 CalcResult: type: object required: - goods_value - freight - insurance - customs_value - duty_amount - taxes_amount - fees_amount - total_landed_cost - currency - calculation_date - breakdown properties: goods_value: type: number freight: type: number insurance: type: number customs_value: type: number duty_amount: type: number taxes_amount: type: number fees_amount: type: number total_landed_cost: type: number currency: type: string calculation_date: type: string format: date breakdown: type: array items: $ref: '#/components/schemas/CalcBreakdownLayer' de_minimis: type: object properties: applies: type: boolean threshold: type: number nullable: true currency: type: string nullable: true warnings: type: array items: type: string ComplianceFlag: type: object required: - kind - severity - title properties: kind: type: string enum: - section_122 - fx_rate - data_gap - restriction - pga - ad_cvd - fta_opportunity - fta_qualified - unit_price_deviation severity: type: string enum: - info - warning - critical title: type: string detail: type: string nullable: true source: type: string nullable: true source_url: type: string format: uri nullable: true legal_citation: type: string nullable: true hs_code: type: string nullable: true restriction_type: type: string nullable: true Error: type: object required: - error properties: error: type: string code: type: string message: type: string detail: type: string issues: type: array items: type: object CalcBreakdownLayer: type: object required: - code - amount properties: code: type: string description: | Duty / tax / fee code (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, etc.). amount: type: number rate: type: number nullable: true exempted: type: boolean default: false note: type: string nullable: true headers: XRateLimitLimit: description: Total requests allowed in the current window. schema: type: integer example: 1000 XRateLimitRemaining: description: Requests remaining in the current window. schema: type: integer example: 987 XRateLimitReset: description: Unix epoch seconds when the window resets. schema: type: integer example: 1755273600 responses: BadRequest: description: Request body failed validation. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: invalid body issues: - path: - destination_country message: String must contain exactly 2 character(s) Unauthorized: description: Missing or invalid API key. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: unauthorized PaymentRequired: description: >- Quota exhausted for the current plan. Upgrade or wait for the monthly reset. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: quota_exceeded code: QUOTA_EXCEEDED message: >- Monthly quota exhausted. Upgrade at https://www.landedfees.com/pricing. UnprocessableEntity: description: >- Semantic failure (missing HS code, unsupported destination, domestic shipment). content: application/json: schema: $ref: '#/components/schemas/Error' example: error: missing_hs_code code: MISSING_HS_CODE message: Could not derive HS code for 1 line item(s). TooManyRequests: description: Rate limit exceeded. Retry after the reset window. headers: Retry-After: description: Seconds to wait before retrying. schema: type: integer content: application/json: schema: $ref: '#/components/schemas/Error' example: error: rate_limited code: RATE_LIMITED message: Too many requests. Retry after 60 seconds. InternalError: description: Unexpected server error. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: internal detail: engine error securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: sk_live description: | API key issued from the LandedFees dashboard under Settings > API keys. Format: `sk_live_...` (production) or `sk_test_...` (sandbox). Pass in the `Authorization: Bearer ` header. ````