Japan Sellability API
Developer documentation
Assess whether a product can proceed toward sale in Japan, what conditions apply, what information is still missing, and which official sources support the result.
Four explicit outcomes. SELLABLE, SELLABLE_WITH_CONDITIONS, REVIEW_REQUIRED, and NOT_SELLABLE preserve uncertainty instead of guessing.
Quick Start
Make the first request
Create a free account, issue an API key in Dashboard, and send the key only in the Bearer header.
curl -X POST https://api.japanapistore.com/v1/sellability/check \
-H "Authorization: Bearer ${JAPAN_API_KEY}" \
-H "Content-Type: application/json" \
-d '{
"product_name": "Bluetooth speaker",
"category": "Radio Equipment",
"description": "Portable consumer speaker with Bluetooth connectivity",
"wireless_function": true,
"origin_country": "US"
}'Authentication
Use the existing JAPAN API STORE API key: Authorization: Bearer jap_live_…. Never place the key in a URL, client bundle, analytics event, or repository.
POST /v1/sellability/check
The endpoint uses the same API-key, plan, Usage, and rate-limit boundary as Address Mix and Business Mix. Anonymous website checks use a separate constrained endpoint and do not accept API keys.
Request
product_name and category are required. Add description, origin_country, materials, ingredients, intended use, electrical and wireless details when known. Incomplete input still returns a conservative current assessment plus the missing information needed to improve it.
View exact request schema
{
"$id": "SellabilityRequest",
"additionalProperties": false,
"type": "object",
"required": [
"product_name",
"category"
],
"properties": {
"product_name": {
"minLength": 1,
"maxLength": 160,
"type": "string"
},
"category": {
"anyOf": [
{
"const": "Food",
"type": "string"
},
{
"const": "Beverage",
"type": "string"
},
{
"const": "Supplement",
"type": "string"
},
{
"const": "Cosmetics",
"type": "string"
},
{
"const": "Pharmaceutical",
"type": "string"
},
{
"const": "Quasi-drug",
"type": "string"
},
{
"const": "Medical Device",
"type": "string"
},
{
"const": "Electrical Appliance",
"type": "string"
},
{
"const": "Electronics",
"type": "string"
},
{
"const": "Battery",
"type": "string"
},
{
"const": "Toy",
"type": "string"
},
{
"const": "Baby Product",
"type": "string"
},
{
"const": "Clothing",
"type": "string"
},
{
"const": "Textile",
"type": "string"
},
{
"const": "Chemical",
"type": "string"
},
{
"const": "Detergent",
"type": "string"
},
{
"const": "Household Product",
"type": "string"
},
{
"const": "Furniture",
"type": "string"
},
{
"const": "Kitchenware",
"type": "string"
},
{
"const": "Container / Packaging",
"type": "string"
},
{
"const": "Agricultural Product",
"type": "string"
},
{
"const": "Plant",
"type": "string"
},
{
"const": "Animal Product",
"type": "string"
},
{
"const": "Pet Product",
"type": "string"
},
{
"const": "Pet Food",
"type": "string"
},
{
"const": "Alcohol",
"type": "string"
},
{
"const": "Tobacco / Nicotine",
"type": "string"
},
{
"const": "Vehicle / Parts",
"type": "string"
},
{
"const": "Machinery",
"type": "string"
},
{
"const": "Radio Equipment",
"type": "string"
},
{
"const": "Luxury Goods",
"type": "string"
},
{
"const": "Wildlife Product",
"type": "string"
},
{
"const": "General Goods",
"type": "string"
},
{
"const": "Unknown",
"type": "string"
}
]
},
"description": {
"minLength": 1,
"maxLength": 1000,
"type": "string"
},
"intended_use": {
"minLength": 1,
"maxLength": 500,
"type": "string"
},
"materials": {
"maxItems": 16,
"type": "array",
"items": {
"minLength": 1,
"maxLength": 120,
"type": "string"
}
},
"uses_power": {
"type": "boolean"
},
"wireless_function": {
"type": "boolean"
},
"food_contact": {
"type": "boolean"
},
"chemicals_or_ingredients": {
"maxItems": 32,
"type": "array",
"items": {
"minLength": 1,
"maxLength": 160,
"type": "string"
}
},
"medical_purpose": {
"type": "boolean"
},
"target_age": {
"anyOf": [
{
"minimum": 0,
"maximum": 150,
"type": "number"
},
{
"minLength": 1,
"maxLength": 60,
"type": "string"
}
]
},
"origin_country": {
"minLength": 2,
"maxLength": 80,
"type": "string"
},
"hs_code": {
"minLength": 4,
"maxLength": 16,
"pattern": "^[0-9. -]+$",
"type": "string"
},
"notes": {
"minLength": 1,
"maxLength": 1000,
"type": "string"
},
"follow_up_answers": {
"maxItems": 24,
"type": "array",
"items": {
"additionalProperties": false,
"type": "object",
"required": [
"field",
"answer"
],
"properties": {
"field": {
"anyOf": [
{
"const": "intended_use",
"type": "string"
},
{
"const": "origin_country",
"type": "string"
},
{
"const": "materials",
"type": "string"
},
{
"const": "ingredients",
"type": "string"
},
{
"const": "food_contact",
"type": "string"
},
{
"const": "medical_purpose",
"type": "string"
},
{
"const": "target_age",
"type": "string"
},
{
"const": "uses_power",
"type": "string"
},
{
"const": "wireless_function",
"type": "string"
},
{
"const": "rated_voltage",
"type": "string"
},
{
"const": "technical_conformity_number",
"type": "string"
},
{
"const": "approval_or_certification_number",
"type": "string"
},
{
"const": "certification",
"type": "string"
},
{
"const": "cas_numbers",
"type": "string"
},
{
"const": "official_scope_evidence",
"type": "string"
},
{
"const": "exact_official_identifier",
"type": "string"
},
{
"const": "hs_code",
"type": "string"
},
{
"const": "frequency_bands",
"type": "string"
},
{
"const": "radio_frequency",
"type": "string"
},
{
"const": "radio_protocols",
"type": "string"
},
{
"const": "transmit_power",
"type": "string"
},
{
"const": "magnet_specification",
"type": "string"
},
{
"const": "scientific_name",
"type": "string"
},
{
"const": "origin_region",
"type": "string"
},
{
"const": "export_country",
"type": "string"
},
{
"const": "product_form",
"type": "string"
},
{
"const": "product_part",
"type": "string"
},
{
"const": "plant_part",
"type": "string"
},
{
"const": "animal_part",
"type": "string"
},
{
"const": "processing_state",
"type": "string"
},
{
"const": "processing_method",
"type": "string"
},
{
"const": "packaging",
"type": "string"
},
{
"const": "prior_use",
"type": "string"
},
{
"const": "government_certificate",
"type": "string"
},
{
"const": "species",
"type": "string"
},
{
"const": "intended_species",
"type": "string"
},
{
"const": "target_species",
"type": "string"
},
{
"const": "importer_role",
"type": "string"
},
{
"const": "business_role",
"type": "string"
},
{
"const": "fertilizer_registration_number",
"type": "string"
},
{
"const": "official_registration_scope",
"type": "string"
},
{
"const": "import_purpose",
"type": "string"
},
{
"const": "annual_quantity_kg",
"type": "string"
},
{
"const": "heat_temperature_c",
"type": "string"
},
{
"const": "heat_duration_seconds",
"type": "string"
},
{
"const": "designated_facility_confirmed",
"type": "string"
},
{
"const": "health_certificate_confirmed",
"type": "string"
},
{
"const": "import_prohibited",
"type": "string"
},
{
"const": "matches_certificate_required_rule",
"type": "string"
},
{
"const": "frozen_solid",
"type": "string"
},
{
"const": "frozen_temperature_c",
"type": "string"
},
{
"const": "agricultural_production_use",
"type": "string"
},
{
"const": "all_risk_criteria_confirmed",
"type": "string"
},
{
"const": "legal_notes_confirmed",
"type": "string"
}
]
},
"answer": {
"minLength": 1,
"maxLength": 500,
"type": "string"
}
}
}
}
}
}Response
The response includes a human-readable current decision, deterministic confidence_score from 0 to 100, provisional state, normalized product, prioritized missing information, requirements, restrictions, rules, authorities, official sources, data versions, and usage channel. The existing confidence grade remains available for compatibility.
View exact response schema
{
"$id": "SellabilityResponse",
"additionalProperties": false,
"type": "object",
"required": [
"request_id",
"success",
"status",
"reason",
"guidance",
"confidence",
"normalized_product",
"missing_information",
"requirements",
"restrictions",
"rules_checked",
"authorities_checked",
"official_sources",
"additional_checks",
"data_freshness",
"usage",
"disclaimer"
],
"properties": {
"request_id": {
"pattern": "^req_[a-f0-9]{32}$",
"type": "string"
},
"success": {
"const": true,
"type": "boolean"
},
"status": {
"anyOf": [
{
"const": "SELLABLE",
"type": "string"
},
{
"const": "SELLABLE_WITH_CONDITIONS",
"type": "string"
},
{
"const": "REVIEW_REQUIRED",
"type": "string"
},
{
"const": "NOT_SELLABLE",
"type": "string"
}
]
},
"decision": {
"anyOf": [
{
"const": "SELLABLE",
"type": "string"
},
{
"const": "SELLABLE_WITH_CONDITIONS",
"type": "string"
},
{
"const": "REVIEW_REQUIRED",
"type": "string"
},
{
"const": "NOT_SELLABLE",
"type": "string"
}
]
},
"reason": {
"type": "string"
},
"guidance": {
"type": "string"
},
"confidence": {
"anyOf": [
{
"const": "high",
"type": "string"
},
{
"const": "medium",
"type": "string"
},
{
"const": "low",
"type": "string"
}
]
},
"confidence_score": {
"minimum": 0,
"maximum": 100,
"type": "integer"
},
"confidence_method": {
"const": "deterministic_weighted_rules_v1",
"type": "string"
},
"provisional": {
"type": "boolean"
},
"summary": {
"type": "string"
},
"normalized_product": {
"additionalProperties": false,
"type": "object",
"required": [
"product_name",
"category",
"intended_use",
"origin_country",
"destination_country"
],
"properties": {
"product_name": {
"type": "string"
},
"category": {
"anyOf": [
{
"const": "Food",
"type": "string"
},
{
"const": "Beverage",
"type": "string"
},
{
"const": "Supplement",
"type": "string"
},
{
"const": "Cosmetics",
"type": "string"
},
{
"const": "Pharmaceutical",
"type": "string"
},
{
"const": "Quasi-drug",
"type": "string"
},
{
"const": "Medical Device",
"type": "string"
},
{
"const": "Electrical Appliance",
"type": "string"
},
{
"const": "Electronics",
"type": "string"
},
{
"const": "Battery",
"type": "string"
},
{
"const": "Toy",
"type": "string"
},
{
"const": "Baby Product",
"type": "string"
},
{
"const": "Clothing",
"type": "string"
},
{
"const": "Textile",
"type": "string"
},
{
"const": "Chemical",
"type": "string"
},
{
"const": "Detergent",
"type": "string"
},
{
"const": "Household Product",
"type": "string"
},
{
"const": "Furniture",
"type": "string"
},
{
"const": "Kitchenware",
"type": "string"
},
{
"const": "Container / Packaging",
"type": "string"
},
{
"const": "Agricultural Product",
"type": "string"
},
{
"const": "Plant",
"type": "string"
},
{
"const": "Animal Product",
"type": "string"
},
{
"const": "Pet Product",
"type": "string"
},
{
"const": "Pet Food",
"type": "string"
},
{
"const": "Alcohol",
"type": "string"
},
{
"const": "Tobacco / Nicotine",
"type": "string"
},
{
"const": "Vehicle / Parts",
"type": "string"
},
{
"const": "Machinery",
"type": "string"
},
{
"const": "Radio Equipment",
"type": "string"
},
{
"const": "Luxury Goods",
"type": "string"
},
{
"const": "Wildlife Product",
"type": "string"
},
{
"const": "General Goods",
"type": "string"
},
{
"const": "Unknown",
"type": "string"
}
]
},
"intended_use": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"origin_country": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"hs_code": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"destination_country": {
"const": "JP",
"type": "string"
}
}
},
"missing_information": {
"type": "array",
"items": {
"additionalProperties": false,
"type": "object",
"required": [
"field",
"label",
"question"
],
"properties": {
"field": {
"type": "string"
},
"label": {
"type": "string"
},
"question": {
"type": "string"
},
"priority": {
"anyOf": [
{
"const": "CRITICAL",
"type": "string"
},
{
"const": "HIGH",
"type": "string"
},
{
"const": "MEDIUM",
"type": "string"
},
{
"const": "LOW",
"type": "string"
}
]
},
"reason": {
"type": "string"
}
}
}
},
"requirements": {
"type": "array",
"items": {
"additionalProperties": false,
"type": "object",
"required": [
"type",
"name",
"authority",
"rule_id"
],
"properties": {
"type": {
"type": "string"
},
"name": {
"type": "string"
},
"authority": {
"type": "string"
},
"rule_id": {
"type": "string"
}
}
}
},
"restrictions": {
"type": "array",
"items": {
"additionalProperties": false,
"type": "object",
"required": [
"name",
"authority",
"rule_id"
],
"properties": {
"name": {
"type": "string"
},
"authority": {
"type": "string"
},
"rule_id": {
"type": "string"
}
}
}
},
"rules_checked": {
"type": "array",
"items": {
"type": "string"
}
},
"authorities_checked": {
"type": "array",
"items": {
"type": "string"
}
},
"official_sources": {
"type": "array",
"items": {
"additionalProperties": false,
"type": "object",
"required": [
"source_id",
"source_name",
"organization",
"official_url",
"version",
"last_checked_at",
"retrieved_at",
"effective_from",
"update_frequency",
"status",
"fallback_used"
],
"properties": {
"source_id": {
"type": "string"
},
"source_name": {
"type": "string"
},
"organization": {
"type": "string"
},
"official_url": {
"format": "uri",
"type": "string"
},
"version": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"last_checked_at": {
"anyOf": [
{
"format": "date-time",
"type": "string"
},
{
"type": "null"
}
]
},
"retrieved_at": {
"anyOf": [
{
"format": "date-time",
"type": "string"
},
{
"type": "null"
}
]
},
"effective_from": {
"anyOf": [
{
"format": "date",
"type": "string"
},
{
"type": "null"
}
]
},
"update_frequency": {
"type": "string"
},
"status": {
"type": "string"
},
"fallback_used": {
"type": "boolean"
}
}
}
},
"additional_checks": {
"type": "array",
"items": {
"type": "string"
}
},
"data_freshness": {
"additionalProperties": false,
"type": "object",
"required": [
"engine",
"phase4_version",
"regulatory_version",
"customs_version",
"assessed_at"
],
"properties": {
"engine": {
"const": "phase4",
"type": "string"
},
"phase4_version": {
"type": "string"
},
"regulatory_version": {
"type": "string"
},
"customs_version": {
"type": "string"
},
"assessed_at": {
"format": "date-time",
"type": "string"
}
}
},
"usage": {
"additionalProperties": false,
"type": "object",
"required": [
"counted",
"channel"
],
"properties": {
"counted": {
"type": "boolean"
},
"channel": {
"anyOf": [
{
"const": "anonymous_demo",
"type": "string"
},
{
"const": "api_key",
"type": "string"
}
]
}
}
},
"disclaimer": {
"type": "string"
}
}
}Status definitions
- SELLABLE
- The verified rules evaluated for the supplied facts do not return a blocking or unresolved condition.
- SELLABLE_WITH_CONDITIONS
- Sale may proceed only after the returned conditions and required actions are satisfied.
- REVIEW_REQUIRED
- One or more facts, classifications, or official checks remain unresolved. This is a normal safe result.
- NOT_SELLABLE
- Verified evidence returns a prohibition for the supplied facts and applicable date.
REVIEW_REQUIRED
This is a safe and useful current decision—not a server error. The API still returns a provisional assessment and deterministic confidence score. missing_information lists stable fields with priority, reason, and the exact optional question that can improve confidence.
{
"decision": "REVIEW_REQUIRED",
"confidence_score": 68,
"provisional": true,
"summary": "Sale in Japan may be possible, but one or more regulatory checks still need confirmation.",
"missing_information": [
{
"field": "technical_conformity_number",
"label": "Technical conformity number",
"priority": "CRITICAL",
"reason": "An exact conformity number is needed to verify radio approval.",
"question": "What is the Japanese technical-conformity number for the radio function?"
}
]
}Official sources and freshness
Source records expose the source name, agency, official URL, last check, retrieval date, version, effective date, update frequency, source status, and whether a fallback was used. The response also carries the Phase 4, regulatory, and customs versions. Data updates follow Candidate validation, Golden-case checks, and an atomic Current switch; an invalid update never replaces Current.
Ministry of Agriculture, Forestry and Fisheries (MAFF) / 農林水産省
Japan Sellability API uses public data published by MAFF under the applicable public-data terms. For every matched record, use sources[].dataset, official_url, source_version, fetched_at, applicable_date, raw_source_hash, and normalized_version to trace the exact official snapshot. An absent applicable date is returned as null; it is never inferred.
plant_certificate_exemptions— https://www.maff.go.jp/pps/j/introduction/import/ipcfuyou/index.htmlplant_quarantine_exclusions— https://www.maff.go.jp/pps/j/introduction/import/ifuyou/index.htmlplant_isolation_requirements— https://www.maff.go.jp/pps/j/introduction/import/isyubyou/index.htmlanimal_import_suspensions— https://www.maff.go.jp/aqs/topix/teishijoho.htmlpoultry_regional_suspensions— https://www.maff.go.jp/aqs/topix/im/hpai.htmlaquatic_quarantine_species_diseases— https://www.maff.go.jp/j/syouan/suisan/suisan_boueki/sui_boueki2.htmlaquatic_import_permit_requirements— https://www.maff.go.jp/j/syouan/suisan/suisan_boueki/sui_boueki2.htmlfertilizer_registrations— https://fertilizer-search.maff.go.jp/FertilizerRegistrationSearch
Attribution: Source: Ministry of Agriculture, Forestry and Fisheries of Japan (農林水産省). Public data is used with attribution under Japan's public-data terms; the linked official page remains authoritative.
Errors
- 400 INVALID_REQUEST
- The body does not match the documented schema.
- 401 INVALID_API_KEY
- The API key is absent or invalid.
- 403 API_ACCESS_SUSPENDED
- The project is not currently entitled to call the API.
- 429 RATE_LIMIT_EXCEEDED / PLAN_LIMIT_EXCEEDED
- The current minute or plan limit has been reached.
- 503 DATA_SOURCE_TEMPORARILY_UNAVAILABLE
- The verified source snapshot cannot be used safely.
- 500 INTERNAL_ERROR
- An unexpected internal error occurred; stack traces are never returned.
Rate limits
Limits are plan-specific and enforced by the shared JAPAN API STORE Usage system. The Developer plan includes 1,000 requests per month and 30 requests per minute across the project. Check Dashboard Usage and the current pricing page for the active plan limits.
Disclaimer
Decision support, not a legal guarantee.
JAPAN API STORE organizes official information to support a Japan market review. Rules can change, incomplete inputs remain REVIEW_REQUIRED, and important cases should be confirmed with the relevant authority or a qualified adviser.