{
  "openapi": "3.1.0",
  "info": {
    "title": "Landed Cost API — HS Subheading & Duty Range",
    "version": "1.0.0",
    "summary": "Estimate the import duty on a product: 6-digit HS subheading, general duty rate range, and China Section 301 list exposure from a plain-English description.",
    "description": "Estimate import duty from a plain-English product description: the 6-digit HS subheading, its duty-rate range, and China Section 301 list exposure.\n\nGenerated from the service's own TypeScript contract types, so this document describes what the API actually returns. Operated by EAC Ventures, LLC.\n\nSubscribe, including the free tier: https://rapidapi.com/aervik-labs-aervik-labs-default/api/landed-cost-estimator-hs-code-import-duty-range-api\n\nKnown limits:\n- An estimate at the 6-digit subheading, not a customs classification.\n- Antidumping and countervailing duty orders are not assessed, and each estimate says so.\n- The Section 301 forced-labor duties and Section 232 duties are not assessed.\n\nSources, freshness and live health: https://aerviklabs.com/sources.json (https://aerviklabs.com/data-sources/#hts-tariff-classifier). What we do when something cannot be established: https://aerviklabs.com/trust/\n\nThis OpenAPI document is available under the MIT License (Copyright (c) 2026 EAC Ventures, LLC). Use of the API itself is governed by its Terms of Service, not by that license.",
    "contact": {
      "name": "Aervik Labs",
      "url": "https://aerviklabs.com/about/"
    },
    "x-aervik-provenance": {
      "sources_json": "https://aerviklabs.com/sources.json",
      "data_sources_page": "https://aerviklabs.com/data-sources/#hts-tariff-classifier",
      "trust_page": "https://aerviklabs.com/trust/",
      "read_method": "snapshot",
      "known_limits": [
        "An estimate at the 6-digit subheading, not a customs classification.",
        "Antidumping and countervailing duty orders are not assessed, and each estimate says so.",
        "The Section 301 forced-labor duties and Section 232 duties are not assessed."
      ]
    },
    "termsOfService": "https://tariff.aerviklabs.com/terms"
  },
  "externalDocs": {
    "description": "Product page",
    "url": "https://aerviklabs.com/apis/hts-tariff-classifier/"
  },
  "servers": [
    {
      "url": "https://landed-cost-estimator-hs-code-import-duty-range-api.p.rapidapi.com",
      "description": "RapidAPI gateway"
    }
  ],
  "security": [
    {
      "RapidApiKey": []
    }
  ],
  "paths": {
    "/estimate": {
      "post": {
        "operationId": "estimateLandedCost",
        "summary": "Estimate the 6-digit HS subheading and import duty range for a product description",
        "parameters": [
          {
            "$ref": "#/components/parameters/RapidApiHost"
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EstimateResponse"
                }
              }
            }
          },
          "400": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "405": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "422": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "503": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/EstimateRequest"
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "RapidApiKey": {
        "type": "apiKey",
        "in": "header",
        "name": "X-RapidAPI-Key",
        "description": "Your RapidAPI application key."
      }
    },
    "parameters": {
      "RapidApiHost": {
        "name": "X-RapidAPI-Host",
        "in": "header",
        "required": true,
        "schema": {
          "type": "string",
          "const": "landed-cost-estimator-hs-code-import-duty-range-api.p.rapidapi.com"
        }
      }
    },
    "schemas": {
      "AlternateSubheadingEntry": {
        "type": "object",
        "properties": {
          "hs_code": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "confidence": {
            "type": [
              "number",
              "null"
            ],
            "description": "This alternate's own confidence, 0 to 1, on the same basis as the top-level confidence. Null when the classifier returned none."
          }
        },
        "required": [
          "hs_code",
          "description",
          "confidence"
        ]
      },
      "ApplicableSurchargeEntry": {
        "type": "object",
        "properties": {
          "type": {
            "$ref": "#/components/schemas/SurchargeType"
          },
          "label": {
            "type": "string"
          },
          "note": {
            "type": "string"
          },
          "coverage": {
            "type": "string",
            "enum": [
              "all",
              "some"
            ],
            "description": "China Section 301 list matches only: whether all or only some of the rate lines under this subheading appear on the lists named in `lists`."
          },
          "lists": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SurchargeList"
            }
          }
        },
        "required": [
          "type",
          "label",
          "note"
        ]
      },
      "DutyEstimateRange": {
        "type": "object",
        "properties": {
          "basis": {
            "type": "string"
          },
          "min_pct": {
            "type": [
              "number",
              "null"
            ],
            "description": "Lowest published General (Column 1) percentage rate among the U.S. rate lines under this subheading. Null when none of them carries a percentage rate. An estimate for budgeting, not a duty determination."
          },
          "max_pct": {
            "type": [
              "number",
              "null"
            ],
            "description": "Highest published General (Column 1) percentage rate among the U.S. rate lines under this subheading. Null when none of them carries a percentage rate. An estimate for budgeting, not a duty determination."
          },
          "most_common_rate_pct": {
            "type": [
              "number",
              "null"
            ]
          },
          "most_common_rate_text": {
            "type": "string"
          },
          "lines_at_most_common_rate": {
            "type": "number",
            "description": "How many of the lines counted in tariff_lines_in_subheading carry most_common_rate_text."
          },
          "tariff_lines_in_subheading": {
            "type": "number",
            "description": "Every 8- and 10-digit number the schedule lists under this subheading, so an 8-digit line listed with 10-digit statistical suffixes is counted once itself and once per suffix (6109.10 counts 15: one 8-digit line and its 14 suffixes). lines_at_most_common_rate counts the same way."
          },
          "distinct_published_rates": {
            "type": "number"
          },
          "single_rate_across_subheading": {
            "type": "boolean"
          },
          "includes_non_ad_valorem_rates": {
            "type": "boolean",
            "description": "True when at least one rate line carries a specific or compound rate, so min_pct and max_pct do not describe every line."
          },
          "precision_note": {
            "type": "string",
            "description": "How wide this range is and what it is safe to use for, in plain language. General (Column 1) rates only: Section 301, Section 232, AD/CVD and other additional duties are excluded."
          }
        },
        "required": [
          "basis",
          "min_pct",
          "max_pct",
          "most_common_rate_pct",
          "most_common_rate_text",
          "lines_at_most_common_rate",
          "tariff_lines_in_subheading",
          "distinct_published_rates",
          "single_rate_across_subheading",
          "includes_non_ad_valorem_rates",
          "precision_note"
        ]
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string"
          }
        },
        "required": [
          "error"
        ],
        "description": "Every non-2xx JSON response from the API itself. `error` is a human-readable explanation, not a stable code, and its wording may change: branch on the HTTP status. RapidAPI answers authentication, subscription and rate-limit failures itself, in its own format."
      },
      "EstimateRequest": {
        "type": "object",
        "properties": {
          "description": {
            "type": "string",
            "description": "Plain-English product description: what it is, what it is made of, what it is used for. Required, non-empty, at most 2,000 characters."
          },
          "country_of_origin": {
            "type": "string",
            "description": "Optional ISO 3166-1 alpha-2 code, for example CN. At most 60 characters. The China Section 301 lists are matched only for CN."
          },
          "image_url": {
            "type": "string",
            "description": "Optional. Accepted but not used: matching is text-only."
          },
          "schema_version": {
            "type": "string",
            "const": "1.0",
            "description": "Optional. Omit it or send \"1.0\" for the current response shape. Version 2.0 is not available on the public deployment."
          }
        },
        "required": [
          "description"
        ]
      },
      "EstimateResponse": {
        "type": "object",
        "properties": {
          "hs_code": {
            "type": "string",
            "description": "The 6-digit international Harmonized System subheading, for example 8471.30. Nothing longer is ever returned."
          },
          "classification_level": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "confidence": {
            "type": [
              "number",
              "null"
            ],
            "description": "The match's own confidence, 0 to 1. A self-assessment, not a calibrated probability. Null when the classifier returned no usable confidence; it is never filled in."
          },
          "duty_estimate": {
            "$ref": "#/components/schemas/DutyEstimateRange"
          },
          "applicable_surcharges": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ApplicableSurchargeEntry"
            },
            "description": "Additional-duty signals found among what was checked. An empty list is not a statement that no additional duty applies; see surcharge_coverage."
          },
          "alternate_subheadings": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/AlternateSubheadingEntry"
            }
          },
          "surcharge_coverage": {
            "type": "string",
            "description": "What was and was not checked for additional duties. The China Section 301 lists are matched only for origin CN, and product-specific exclusions are not applied. The Section 301 forced-labor action, other Section 301 actions, Section 232 duties and AD/CVD are NOT assessed for any origin."
          },
          "tariff_schedule_snapshot": {
            "type": "string",
            "description": "Date (YYYY-MM-DD) the bundled U.S. International Trade Commission schedule was retrieved. Every rate in this response is read from that snapshot; later revisions are not reflected."
          },
          "disclaimer": {
            "type": "string"
          },
          "provider": {
            "type": "string"
          }
        },
        "required": [
          "hs_code",
          "classification_level",
          "description",
          "confidence",
          "duty_estimate",
          "applicable_surcharges",
          "alternate_subheadings",
          "surcharge_coverage",
          "tariff_schedule_snapshot",
          "disclaimer",
          "provider"
        ]
      },
      "SurchargeList": {
        "type": "object",
        "properties": {
          "list": {
            "type": "string"
          },
          "additional_rate": {
            "type": "string"
          }
        },
        "required": [
          "list",
          "additional_rate"
        ]
      },
      "SurchargeType": {
        "type": "string",
        "enum": [
          "section_301",
          "section_122"
        ]
      }
    }
  }
}