{ "openapi": "3.1.0", "info": { "title": "Japan Customs Allowance Checker API", "version": "1.0.0", "description": "Arriving in Japan with duty-free shopping? Check the per-person customs allowance (3 bottles of alcohol, 200 cigarettes, 2 oz perfume, ¥200,000 of other goods), see what is over, the estimated simplified duty in yen, and whether you must declare cash over ¥1,000,000.\n\nFree, no API key, CORS open. Fair use: about 120 requests per minute per IP. Also available as MCP tools at https://free-agent-tools.vercel.app/mcp" }, "servers": [ { "url": "https://japan-customs-allowance.vercel.app" } ], "paths": { "/api/check": { "get": { "operationId": "japanCustomsAllowanceCheck", "summary": "Japan Customs duty-free allowance check for travelers entering Japan, with estimated simplified duty in yen and cash declaration", "description": "Per-person duty-free allowance when entering Japan (Japan Customs 7104/7105, as of 2026-10-14): alcohol 3 bottles of about 760 ml (2.28 L), cigarettes 200 OR cigars 50 OR heat-not-burn 10 packages (200 IQOS/glo sticks or 50 Ploom TECH capsules) OR other tobacco 250 g (more than one kind: 250 g total), perfume 2 oz (about 56 ml), other goods ¥200,000 total overseas value (an item kind worth ¥10,000 or less in total is free and not counted; an article worth over ¥200,000 is fully dutiable). Under 20: no alcohol or tobacco allowance; under 6: only items for the child. Accompanied and unaccompanied articles share one allowance. Excess is estimated with the simplified rates (7106): whisky/brandy ¥800/L, rum/gin/vodka ¥500/L, liqueur ¥400/L, distilled ¥300/L, wine/beer/other ¥200/L, cigarettes and heat-not-burn sticks ¥15 each, capsules ¥50 each, other articles 15% of Customs value (overseas price × 0.6), watches/golf clubs/PCs 10% consumption tax only; simplified rates are not applied to an article with Customs value over ¥100,000, cigars or other tobacco (simplifiedDutyApplicable false). Means of payment over ¥1,000,000 (¥100,000 bound for North Korea) must be declared. Returns per-category within/over, excess, estimatedSimplifiedDutyJPY (low) and estimatedSimplifiedDutyHighJPY (strict mixed-tobacco reading), breakdown by tax type truncated to ¥100 as in Customs' worked example, green/red channel, cashDeclarationRequired, warnings, assumptions, sources, rulesAsOf, sharePath, disclaimer. GET takes goods as CSV (80000,120000,150000w,3000x3 — w = duty-free-tariff article such as a watch, xN = quantity, c = for a child); POST takes goods as [{description, valueJPY, quantity, dutyFreeTariff, forChild}] and alcohol as [{type, ml, bottles}].\n\nExample: https://japan-customs-allowance.vercel.app/api/check?ageYears=35&alcoholBottles=4&alcoholType=whisky&cigarettes=200&goods=120000,130000", "parameters": [ { "name": "ageYears", "in": "query", "required": false, "description": "Traveler age. Under 20 = no alcohol/tobacco allowance; under 6 = only items for the child. Default: adult.", "schema": { "type": "number", "description": "Traveler age. Under 20 = no alcohol/tobacco allowance; under 6 = only items for the child. Default: adult.", "minimum": 0, "maximum": 120 } }, { "name": "travelers", "in": "query", "required": false, "description": "People in the same age band whose allowances are pooled (multiplies the per-person allowance).", "schema": { "type": "integer", "description": "People in the same age band whose allowances are pooled (multiplies the per-person allowance).", "default": 1, "minimum": 1, "maximum": 20 } }, { "name": "alcoholBottles", "in": "query", "required": false, "description": "Bottles of alcohol. Without alcoholMl each bottle is assumed 760 ml.", "schema": { "type": "integer", "description": "Bottles of alcohol. Without alcoholMl each bottle is assumed 760 ml.", "minimum": 0 } }, { "name": "alcoholMl", "in": "query", "required": false, "description": "Total alcohol volume in ml (allowance 2,280 ml per adult). Overrides the bottle assumption.", "schema": { "type": "number", "description": "Total alcohol volume in ml (allowance 2,280 ml per adult). Overrides the bottle assumption.", "minimum": 0 } }, { "name": "alcoholType", "in": "query", "required": false, "description": "Type for the simplified rate: whisky/brandy ¥800/L, rum/gin/vodka ¥500/L, liqueur ¥400/L, distilled (shochu) ¥300/L, wine/beer/other ¥200/L.", "schema": { "type": "string", "description": "Type for the simplified rate: whisky/brandy ¥800/L, rum/gin/vodka ¥500/L, liqueur ¥400/L, distilled (shochu) ¥300/L, wine/beer/other ¥200/L.", "enum": [ "whisky", "brandy", "rum", "gin", "vodka", "liqueur", "distilled", "wine", "beer", "other" ], "default": "other" } }, { "name": "cigarettes", "in": "query", "required": false, "description": "Cigarettes (allowance 200; a carton is 200).", "schema": { "type": "integer", "description": "Cigarettes (allowance 200; a carton is 200).", "minimum": 0 } }, { "name": "cigars", "in": "query", "required": false, "description": "Cigars (allowance 50).", "schema": { "type": "integer", "description": "Cigars (allowance 50).", "minimum": 0 } }, { "name": "hnbPackages", "in": "query", "required": false, "description": "Heat-not-burn retail packs (allowance 10). A pack = 20 sticks, or 5 capsules if hnbType=capsules.", "schema": { "type": "integer", "description": "Heat-not-burn retail packs (allowance 10). A pack = 20 sticks, or 5 capsules if hnbType=capsules.", "minimum": 0 } }, { "name": "hnbSticks", "in": "query", "required": false, "description": "Loose heat-not-burn sticks (IQOS / glo). Allowance 200.", "schema": { "type": "integer", "description": "Loose heat-not-burn sticks (IQOS / glo). Allowance 200.", "minimum": 0 } }, { "name": "hnbCapsules", "in": "query", "required": false, "description": "Heat-not-burn capsules / cartridges (Ploom TECH / with). Allowance 50.", "schema": { "type": "integer", "description": "Heat-not-burn capsules / cartridges (Ploom TECH / with). Allowance 50.", "minimum": 0 } }, { "name": "hnbType", "in": "query", "required": false, "description": "What hnbPackages contain.", "schema": { "type": "string", "description": "What hnbPackages contain.", "enum": [ "sticks", "capsules" ], "default": "sticks" } }, { "name": "otherTobaccoGrams", "in": "query", "required": false, "description": "Pipe / roll-your-own / other tobacco in grams (allowance 250 g).", "schema": { "type": "number", "description": "Pipe / roll-your-own / other tobacco in grams (allowance 250 g).", "minimum": 0 } }, { "name": "perfumeMl", "in": "query", "required": false, "description": "Perfume in ml (allowance about 56 ml = 2 oz). Eau de toilette / cologne not counted.", "schema": { "type": "number", "description": "Perfume in ml (allowance about 56 ml = 2 oz). Eau de toilette / cologne not counted.", "minimum": 0 } }, { "name": "perfumeOz", "in": "query", "required": false, "description": "Perfume in ounces (1 oz ≈ 28 ml).", "schema": { "type": "number", "description": "Perfume in ounces (1 oz ≈ 28 ml).", "minimum": 0 } }, { "name": "goodsTotalJPY", "in": "query", "required": false, "description": "Instead of goods: total overseas value of other articles (approximate check).", "schema": { "type": "number", "description": "Instead of goods: total overseas value of other articles (approximate check).", "minimum": 0 } }, { "name": "cashJPY", "in": "query", "required": false, "description": "Cash (yen plus foreign currency in yen) carried by one person.", "schema": { "type": "number", "description": "Cash (yen plus foreign currency in yen) carried by one person.", "minimum": 0 } }, { "name": "paymentInstrumentsJPY", "in": "query", "required": false, "description": "Checks, travelers checks, promissory notes, securities in yen.", "schema": { "type": "number", "description": "Checks, travelers checks, promissory notes, securities in yen.", "minimum": 0 } }, { "name": "boundForNorthKorea", "in": "query", "required": false, "description": "Leaving Japan for North Korea: the declaration threshold is ¥100,000.", "schema": { "type": "boolean", "description": "Leaving Japan for North Korea: the declaration threshold is ¥100,000.", "default": false } }, { "name": "goldBullionKg", "in": "query", "required": false, "description": "Gold bullion carried, kg (over 1 kg of 90%+ purity must be declared).", "schema": { "type": "number", "description": "Gold bullion carried, kg (over 1 kg of 90%+ purity must be declared).", "minimum": 0 } }, { "name": "goods", "in": "query", "required": false, "description": "Other goods as CSV of yen prices of one article: 80000,120000,150000w,3000x3 (xN = quantity, w = duty-free-tariff article like a watch / golf clubs / PC, c = for a child under 6).", "schema": { "type": "string" } }, { "name": "alcohol", "in": "query", "required": false, "description": "Several drinks as CSV type:ml, e.g. whisky:2280,brandy:700.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Result as JSON. Always includes a `disclaimer` field.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Missing or invalid input. The body explains what to send and gives an example." }, "429": { "description": "Too many requests from one IP. Retry after the Retry-After seconds." } } }, "post": { "operationId": "japanCustomsAllowanceCheckPost", "summary": "Japan Customs duty-free allowance check for travelers entering Japan, with estimated simplified duty in yen and cash declaration (JSON body)", "description": "Per-person duty-free allowance when entering Japan (Japan Customs 7104/7105, as of 2026-10-14): alcohol 3 bottles of about 760 ml (2.28 L), cigarettes 200 OR cigars 50 OR heat-not-burn 10 packages (200 IQOS/glo sticks or 50 Ploom TECH capsules) OR other tobacco 250 g (more than one kind: 250 g total), perfume 2 oz (about 56 ml), other goods ¥200,000 total overseas value (an item kind worth ¥10,000 or less in total is free and not counted; an article worth over ¥200,000 is fully dutiable). Under 20: no alcohol or tobacco allowance; under 6: only items for the child. Accompanied and unaccompanied articles share one allowance. Excess is estimated with the simplified rates (7106): whisky/brandy ¥800/L, rum/gin/vodka ¥500/L, liqueur ¥400/L, distilled ¥300/L, wine/beer/other ¥200/L, cigarettes and heat-not-burn sticks ¥15 each, capsules ¥50 each, other articles 15% of Customs value (overseas price × 0.6), watches/golf clubs/PCs 10% consumption tax only; simplified rates are not applied to an article with Customs value over ¥100,000, cigars or other tobacco (simplifiedDutyApplicable false). Means of payment over ¥1,000,000 (¥100,000 bound for North Korea) must be declared. Returns per-category within/over, excess, estimatedSimplifiedDutyJPY (low) and estimatedSimplifiedDutyHighJPY (strict mixed-tobacco reading), breakdown by tax type truncated to ¥100 as in Customs' worked example, green/red channel, cashDeclarationRequired, warnings, assumptions, sources, rulesAsOf, sharePath, disclaimer. GET takes goods as CSV (80000,120000,150000w,3000x3 — w = duty-free-tariff article such as a watch, xN = quantity, c = for a child); POST takes goods as [{description, valueJPY, quantity, dutyFreeTariff, forChild}] and alcohol as [{type, ml, bottles}].", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "required": [], "properties": { "ageYears": { "type": "number", "description": "Traveler age. Under 20 = no alcohol/tobacco allowance; under 6 = only items for the child. Default: adult.", "minimum": 0, "maximum": 120 }, "travelers": { "type": "integer", "description": "People in the same age band whose allowances are pooled (multiplies the per-person allowance).", "default": 1, "minimum": 1, "maximum": 20 }, "alcoholBottles": { "type": "integer", "description": "Bottles of alcohol. Without alcoholMl each bottle is assumed 760 ml.", "minimum": 0 }, "alcoholMl": { "type": "number", "description": "Total alcohol volume in ml (allowance 2,280 ml per adult). Overrides the bottle assumption.", "minimum": 0 }, "alcoholType": { "type": "string", "description": "Type for the simplified rate: whisky/brandy ¥800/L, rum/gin/vodka ¥500/L, liqueur ¥400/L, distilled (shochu) ¥300/L, wine/beer/other ¥200/L.", "enum": [ "whisky", "brandy", "rum", "gin", "vodka", "liqueur", "distilled", "wine", "beer", "other" ], "default": "other" }, "alcohol": { "type": "array", "description": "POST: several drinks [{type, ml, bottles}]. GET: CSV type:ml, e.g. whisky:2280,brandy:700.", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "whisky", "brandy", "rum", "gin", "vodka", "liqueur", "distilled", "wine", "beer", "other" ] }, "ml": { "type": "number" }, "bottles": { "type": "integer" } } } }, "cigarettes": { "type": "integer", "description": "Cigarettes (allowance 200; a carton is 200).", "minimum": 0 }, "cigars": { "type": "integer", "description": "Cigars (allowance 50).", "minimum": 0 }, "hnbPackages": { "type": "integer", "description": "Heat-not-burn retail packs (allowance 10). A pack = 20 sticks, or 5 capsules if hnbType=capsules.", "minimum": 0 }, "hnbSticks": { "type": "integer", "description": "Loose heat-not-burn sticks (IQOS / glo). Allowance 200.", "minimum": 0 }, "hnbCapsules": { "type": "integer", "description": "Heat-not-burn capsules / cartridges (Ploom TECH / with). Allowance 50.", "minimum": 0 }, "hnbType": { "type": "string", "description": "What hnbPackages contain.", "enum": [ "sticks", "capsules" ], "default": "sticks" }, "otherTobaccoGrams": { "type": "number", "description": "Pipe / roll-your-own / other tobacco in grams (allowance 250 g).", "minimum": 0 }, "perfumeMl": { "type": "number", "description": "Perfume in ml (allowance about 56 ml = 2 oz). Eau de toilette / cologne not counted.", "minimum": 0 }, "perfumeOz": { "type": "number", "description": "Perfume in ounces (1 oz ≈ 28 ml).", "minimum": 0 }, "goods": { "type": "array", "description": "Other articles. POST: [{description, valueJPY (overseas price of ONE article), quantity, dutyFreeTariff, forChild}]. GET: CSV like 80000,120000,150000w,3000x3.", "items": { "type": "object", "properties": { "description": { "type": "string" }, "valueJPY": { "type": "number" }, "quantity": { "type": "integer" }, "dutyFreeTariff": { "type": "boolean" }, "forChild": { "type": "boolean" } }, "required": [ "valueJPY" ] } }, "goodsTotalJPY": { "type": "number", "description": "Instead of goods: total overseas value of other articles (approximate check).", "minimum": 0 }, "cashJPY": { "type": "number", "description": "Cash (yen plus foreign currency in yen) carried by one person.", "minimum": 0 }, "paymentInstrumentsJPY": { "type": "number", "description": "Checks, travelers checks, promissory notes, securities in yen.", "minimum": 0 }, "boundForNorthKorea": { "type": "boolean", "description": "Leaving Japan for North Korea: the declaration threshold is ¥100,000.", "default": false }, "goldBullionKg": { "type": "number", "description": "Gold bullion carried, kg (over 1 kg of 90%+ purity must be declared).", "minimum": 0 } } } } } }, "responses": { "200": { "description": "Result as JSON. Always includes a `disclaimer` field.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Missing or invalid input. The body explains what to send and gives an example." }, "429": { "description": "Too many requests from one IP. Retry after the Retry-After seconds." } } } }, "/api/rules": { "get": { "operationId": "japanCustomsAllowanceRules", "summary": "Full Japan Customs duty-free allowance table, simplified duty rates, cash declaration rule, assumptions and sources", "description": "Returns the dated per-person allowance (alcohol, tobacco, perfume, other goods), age rules, simplified duty rates (7106) and where they do not apply, the means-of-payment declaration thresholds, the assumptions this calculator makes, sources and the disclaimer. No inputs.", "responses": { "200": { "description": "Rules JSON with rulesAsOf and sources.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } }, "post": { "operationId": "japanCustomsAllowanceRulesPost", "summary": "Full Japan Customs duty-free allowance table, simplified duty rates, cash declaration rule, assumptions and sources", "description": "Returns the dated per-person allowance (alcohol, tobacco, perfume, other goods), age rules, simplified duty rates (7106) and where they do not apply, the means-of-payment declaration thresholds, the assumptions this calculator makes, sources and the disclaimer. No inputs.", "responses": { "200": { "description": "Rules JSON with rulesAsOf and sources.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } } } }