{
  "openapi": "3.1.0",
  "info": {
    "title": "Japan Tax-Free Refund Checker API",
    "version": "1.0.0",
    "description": "From November 1, 2026, Japan refunds consumption tax at departure instead of removing it at the till. Check which receipts qualify, how much tax you get back, and your 90-day customs deadline.\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-tax-free-refund.vercel.app"
    }
  ],
  "paths": {
    "/api/refund": {
      "get": {
        "operationId": "japanTaxFreeRefundCheck",
        "summary": "Japan tax-free shopping refund check (refund method from 2026-11-01): per store/day eligibility, refund amount, 90-day deadline",
        "description": "Japan switches tax-free shopping to a refund method for purchases from 2026-11-01: visitors pay the tax-inclusive price and get the consumption tax back after customs confirms export on departure (before checking bags) within 90 days of purchase. Groups receipts by store + purchase date, checks the ¥5,000 tax-exclusive minimum per store per day, computes the tax inside each price as floor(amount*rate/(100+rate)) for 10% or 8%, the customs deadline (purchase date + 90 days), and whether your departure date is in time. Purchases before 2026-11-01 are labelled regime tax_off (tax removed at the till, nothing to claim). Returns maxRefundJPY (before any operator fee), notes, a departure checklist, official sources, rulesAsOf, and a disclaimer. GET takes one receipt as query params; POST takes {departureDate, receipts:[...]}.\n\nExample: https://japan-tax-free-refund.vercel.app/api/refund?amount=16500&rate=10&purchaseDate=2026-11-12&departureDate=2026-11-20",
        "parameters": [
          {
            "name": "amount",
            "in": "query",
            "required": false,
            "description": "GET single receipt: amount in whole yen (tax-inclusive unless priceIncludesTax=false).",
            "schema": {
              "type": "integer",
              "description": "GET single receipt: amount in whole yen (tax-inclusive unless priceIncludesTax=false).",
              "minimum": 1
            }
          },
          {
            "name": "rate",
            "in": "query",
            "required": false,
            "description": "GET single receipt: consumption tax rate, 10 (standard) or 8 (reduced: food, non-alcoholic drinks).",
            "schema": {
              "type": "integer",
              "description": "GET single receipt: consumption tax rate, 10 (standard) or 8 (reduced: food, non-alcoholic drinks).",
              "enum": [
                "10",
                "8"
              ],
              "default": 10
            }
          },
          {
            "name": "purchaseDate",
            "in": "query",
            "required": false,
            "description": "GET single receipt: YYYY-MM-DD. Before 2026-11-01 = old tax_off regime.",
            "schema": {
              "type": "string",
              "description": "GET single receipt: YYYY-MM-DD. Before 2026-11-01 = old tax_off regime."
            }
          },
          {
            "name": "store",
            "in": "query",
            "required": false,
            "description": "GET single receipt: store name (optional).",
            "schema": {
              "type": "string",
              "description": "GET single receipt: store name (optional).",
              "default": "Store"
            }
          },
          {
            "name": "priceIncludesTax",
            "in": "query",
            "required": false,
            "description": "GET single receipt: whether amount includes tax.",
            "schema": {
              "type": "boolean",
              "description": "GET single receipt: whether amount includes tax.",
              "default": true
            }
          },
          {
            "name": "category",
            "in": "query",
            "required": false,
            "description": "Optional: general, consumable, bullion, tax_exempt. bullion and tax_exempt are excluded.",
            "schema": {
              "type": "string",
              "description": "Optional: general, consumable, bullion, tax_exempt. bullion and tax_exempt are excluded.",
              "enum": [
                "general",
                "consumable",
                "bullion",
                "tax_exempt"
              ]
            }
          },
          {
            "name": "departureDate",
            "in": "query",
            "required": false,
            "description": "YYYY-MM-DD of your final departure from Japan. Checked against each group's 90-day deadline.",
            "schema": {
              "type": "string",
              "description": "YYYY-MM-DD of your final departure from Japan. Checked against each group's 90-day deadline."
            }
          }
        ],
        "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": "japanTaxFreeRefundCheckPost",
        "summary": "Japan tax-free shopping refund check (refund method from 2026-11-01): per store/day eligibility, refund amount, 90-day deadline (JSON body)",
        "description": "Japan switches tax-free shopping to a refund method for purchases from 2026-11-01: visitors pay the tax-inclusive price and get the consumption tax back after customs confirms export on departure (before checking bags) within 90 days of purchase. Groups receipts by store + purchase date, checks the ¥5,000 tax-exclusive minimum per store per day, computes the tax inside each price as floor(amount*rate/(100+rate)) for 10% or 8%, the customs deadline (purchase date + 90 days), and whether your departure date is in time. Purchases before 2026-11-01 are labelled regime tax_off (tax removed at the till, nothing to claim). Returns maxRefundJPY (before any operator fee), notes, a departure checklist, official sources, rulesAsOf, and a disclaimer. GET takes one receipt as query params; POST takes {departureDate, receipts:[...]}.",
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [],
                "properties": {
                  "amount": {
                    "type": "integer",
                    "description": "GET single receipt: amount in whole yen (tax-inclusive unless priceIncludesTax=false).",
                    "minimum": 1
                  },
                  "rate": {
                    "type": "integer",
                    "description": "GET single receipt: consumption tax rate, 10 (standard) or 8 (reduced: food, non-alcoholic drinks).",
                    "enum": [
                      "10",
                      "8"
                    ],
                    "default": 10
                  },
                  "purchaseDate": {
                    "type": "string",
                    "description": "GET single receipt: YYYY-MM-DD. Before 2026-11-01 = old tax_off regime."
                  },
                  "store": {
                    "type": "string",
                    "description": "GET single receipt: store name (optional).",
                    "default": "Store"
                  },
                  "priceIncludesTax": {
                    "type": "boolean",
                    "description": "GET single receipt: whether amount includes tax.",
                    "default": true
                  },
                  "category": {
                    "type": "string",
                    "description": "Optional: general, consumable, bullion, tax_exempt. bullion and tax_exempt are excluded.",
                    "enum": [
                      "general",
                      "consumable",
                      "bullion",
                      "tax_exempt"
                    ]
                  },
                  "departureDate": {
                    "type": "string",
                    "description": "YYYY-MM-DD of your final departure from Japan. Checked against each group's 90-day deadline."
                  },
                  "receipts": {
                    "type": "array",
                    "description": "POST: list of receipts. Use instead of amount/rate/purchaseDate for more than one receipt.",
                    "items": {
                      "type": "object",
                      "properties": {
                        "store": {
                          "type": "string",
                          "description": "Store/branch name. Receipts are grouped by store + purchaseDate."
                        },
                        "purchaseDate": {
                          "type": "string",
                          "description": "YYYY-MM-DD"
                        },
                        "amount": {
                          "type": "integer",
                          "description": "Whole yen."
                        },
                        "rate": {
                          "type": "integer",
                          "enum": [
                            10,
                            8
                          ],
                          "description": "10 standard, 8 reduced (food, non-alcoholic drinks)."
                        },
                        "priceIncludesTax": {
                          "type": "boolean",
                          "description": "Default true."
                        },
                        "category": {
                          "type": "string",
                          "enum": [
                            "general",
                            "consumable",
                            "bullion",
                            "tax_exempt"
                          ],
                          "description": "Optional. bullion and tax_exempt are never refundable."
                        }
                      },
                      "required": [
                        "store",
                        "purchaseDate",
                        "amount",
                        "rate"
                      ]
                    }
                  }
                }
              }
            }
          }
        },
        "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": "japanTaxFreeRules",
        "summary": "Plain explanation of both Japan tax-free regimes (tax_off before 2026-11-01, refund from 2026-11-01)",
        "description": "Returns the dated rules table, tax math, checklist, sources, and disclaimer. No inputs.",
        "responses": {
          "200": {
            "description": "Rules JSON with rulesAsOf and sources.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          }
        }
      }
    }
  }
}