{"openapi":"3.1.0","info":{"title":"TariffsTool landed cost API","version":"v1","summary":"Free US import duty and landed-cost estimate for sourcing agents.","description":"Returns the same stacked duty as https://www.tariffstool.com/tariff-calculator (HTS mode), including a listed-line Section 232 pharmaceuticals layer and a prohibited status with no duty figure when the calculator marks an import ban. Merchandise Processing Fee and Harbor Maintenance Fee estimates use the FY2026 formulas in the calculator. curated static snapshot, not a live USITC feed. Estimate only. Not customs, legal, or tax advice. Verify with a licensed customs broker. Attribution: link to https://www.tariffstool.com when displaying results. Optional self-issued key via the x-api-key header (tt_free_ plus at least 8 characters). No signup."},"servers":[{"url":"https://www.tariffstool.com"}],"paths":{"/api/v1/landed-cost":{"get":{"operationId":"getLandedCost","summary":"Estimate landed cost from query parameters.","parameters":[{"name":"hts","in":"query","required":true,"schema":{"type":"string"},"description":"HTS code, 4–10 digits. Dots optional."},{"name":"origin","in":"query","required":true,"schema":{"type":"string"},"description":"ISO 3166-1 alpha-2 or alpha-3 code, or a TariffsTool country slug."},{"name":"customs_value","in":"query","required":true,"schema":{"type":"number","exclusiveMinimum":0},"description":"Dutiable customs value in USD. Not multiplied by quantity."},{"name":"mode","in":"query","required":false,"schema":{"type":"string","enum":["ocean","air","truck","rail"]},"description":"Harbor Maintenance Fee is estimated only when mode is ocean."},{"name":"quantity","in":"query","required":false,"schema":{"type":"number","exclusiveMinimum":0},"description":"Echoed for the caller. Does not change duty."},{"name":"freight","in":"query","required":false,"schema":{"type":"number","minimum":0},"description":"Your freight estimate in USD. Added to landed cost, not to duty."},{"name":"insurance","in":"query","required":false,"schema":{"type":"number","minimum":0}},{"name":"other_fees","in":"query","required":false,"schema":{"type":"number","minimum":0},"description":"Brokerage, bond, or similar. Added to landed cost, not to duty."}],"responses":{"200":{"description":"Estimate.","content":{"application/json":{"schema":{"type":"object","required":["input","status","import_ban","total_duty","effective_rate_pct","total_landed_cost","layers","mpf","hmf","note","meta","disclaimer"],"properties":{"input":{"type":"object"},"status":{"type":"string","enum":["duty","prohibited"],"description":"prohibited is an import ban. Duty figures are null."},"import_ban":{"type":"boolean"},"total_duty":{"type":["number","null"]},"effective_rate_pct":{"type":["number","null"]},"total_landed_cost":{"type":["number","null"]},"layers":{"type":"array","items":{"type":"object","required":["name","legal_authority","program","rate_pct","amount_usd","struck_down","citation","citation_status"],"properties":{"name":{"type":"string","description":"Calculator breakdown label."},"legal_authority":{"type":"string"},"program":{"type":"string","description":"Layer key. Matches src/lib/citations.ts when that table has the program."},"rate_pct":{"type":"number"},"amount_usd":{"type":"number"},"struck_down":{"type":"boolean","description":"True for the former IEEPA line the calculator shows struck through. amount_usd is 0 and it is not part of total_duty."},"citation":{"description":"Copied from citationsFor for this program and HTS, or a program-wide row when the table has one. Null when the table has no citation for the program.","oneOf":[{"type":"object","required":["federal_register","document_number","url","pdf_url","effective_date","hts"],"properties":{"federal_register":{"type":"string"},"document_number":{"type":"string"},"url":{"type":"string"},"pdf_url":{"type":"string"},"effective_date":{"type":["string","null"],"description":"ISO date copied from the repo, or null when the notice has none."},"hts":{"type":"string","description":"HTS the quote was filed under. Empty when the quote is program-wide."}}},{"type":"null"}]},"citation_status":{"type":"string","enum":["cited","pending"]}}}},"mpf":{"type":["object","null"]},"hmf":{"type":["object","null"]},"note":{"type":["string","null"]},"meta":{"type":"object","properties":{"rates_last_verified":{"type":"string"},"changes_through":{"type":"string"},"data_source":{"type":"string","const":"curated static snapshot, not a live USITC feed"},"api_version":{"type":"string","const":"v1"}}},"disclaimer":{"type":"string","const":"Estimate only. Not customs, legal, or tax advice. Verify with a licensed customs broker."}}}}}},"400":{"description":"Invalid input."},"404":{"description":"Unknown HTS heading or country."},"429":{"description":"Rate limit. See Retry-After.","headers":{"Retry-After":{"schema":{"type":"string"}}}}}},"post":{"operationId":"postLandedCost","summary":"Estimate landed cost from a JSON body.","parameters":[{"name":"x-api-key","in":"header","required":false,"schema":{"type":"string"},"description":"Optional self-issued key, format tt_free_… . Not required. There is no key server."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["hts","origin","customs_value"],"properties":{"hts":{"type":"string"},"origin":{"type":"string"},"customs_value":{"type":"number","exclusiveMinimum":0},"mode":{"type":"string","enum":["ocean","air","truck","rail"]},"quantity":{"type":"number","exclusiveMinimum":0},"freight":{"type":"number","minimum":0},"insurance":{"type":"number","minimum":0},"other_fees":{"type":"number","minimum":0}}},"example":{"hts":"7208","origin":"CN","customs_value":10000,"mode":"ocean"}}}},"responses":{"200":{"description":"Estimate.","content":{"application/json":{"schema":{"type":"object","required":["input","status","import_ban","total_duty","effective_rate_pct","total_landed_cost","layers","mpf","hmf","note","meta","disclaimer"],"properties":{"input":{"type":"object"},"status":{"type":"string","enum":["duty","prohibited"],"description":"prohibited is an import ban. Duty figures are null."},"import_ban":{"type":"boolean"},"total_duty":{"type":["number","null"]},"effective_rate_pct":{"type":["number","null"]},"total_landed_cost":{"type":["number","null"]},"layers":{"type":"array","items":{"type":"object","required":["name","legal_authority","program","rate_pct","amount_usd","struck_down","citation","citation_status"],"properties":{"name":{"type":"string","description":"Calculator breakdown label."},"legal_authority":{"type":"string"},"program":{"type":"string","description":"Layer key. Matches src/lib/citations.ts when that table has the program."},"rate_pct":{"type":"number"},"amount_usd":{"type":"number"},"struck_down":{"type":"boolean","description":"True for the former IEEPA line the calculator shows struck through. amount_usd is 0 and it is not part of total_duty."},"citation":{"description":"Copied from citationsFor for this program and HTS, or a program-wide row when the table has one. Null when the table has no citation for the program.","oneOf":[{"type":"object","required":["federal_register","document_number","url","pdf_url","effective_date","hts"],"properties":{"federal_register":{"type":"string"},"document_number":{"type":"string"},"url":{"type":"string"},"pdf_url":{"type":"string"},"effective_date":{"type":["string","null"],"description":"ISO date copied from the repo, or null when the notice has none."},"hts":{"type":"string","description":"HTS the quote was filed under. Empty when the quote is program-wide."}}},{"type":"null"}]},"citation_status":{"type":"string","enum":["cited","pending"]}}}},"mpf":{"type":["object","null"]},"hmf":{"type":["object","null"]},"note":{"type":["string","null"]},"meta":{"type":"object","properties":{"rates_last_verified":{"type":"string"},"changes_through":{"type":"string"},"data_source":{"type":"string","const":"curated static snapshot, not a live USITC feed"},"api_version":{"type":"string","const":"v1"}}},"disclaimer":{"type":"string","const":"Estimate only. Not customs, legal, or tax advice. Verify with a licensed customs broker."}}}}}},"400":{"description":"Invalid input."},"404":{"description":"Unknown HTS heading or country."},"429":{"description":"Rate limit. See Retry-After."}}}}}}