Japan VAT Export Exemption Validator

Validate Japan consumption-tax (消費税) export-exemption transactions in seconds. Each transaction is checked against 消費税法 第7条1項, 国税庁通達 11-7-4 (carrier-document requirements), and 適格請求書 issuer-number checksums — the three things a 税務署 audit will actually look at.

Built for Japan-based merchants selling cross-border on Shopify, BASE, Stores, or custom storefronts, and for the tax accountants (税理士) who file their returns.

What it validates

For every transaction in a single Apify run:

• Shipping country: Must not be JP for an export exemption claim
• Carrier documents: At least one customs export declaration (輸出許可通知書), EMS dispatch note (差出票), bill of lading, air waybill, or DHL/FedEx equivalent — and the right one for the transaction value bucket (¥200,000 / ¥2M / ¥3M thresholds)
• Retention horizon: 7-year document-retention rule (消費税法施行令 第50条)
• Qualified-invoice issuer number (適格請求書, T + 13 digits): ISO 7064 MOD 9 checksum validation
• Evidence hash chain: Optional RFC 3161 timestamp chain marker for audit defense

When to use it

• Year-end review: Before filing your 消費税 return, batch-validate the year's export transactions
• Pre-audit hardening: When you receive a 税務調査 notice, run every export claim through the validator to surface gaps proactively
• Onboarding 税理士: Send your accountant a single Apify dataset URL instead of an Excel sheet — they can re-run validation as your data updates
• CI / nightly check: Schedule the Actor to re-validate the last 90 days of Shopify orders nightly via Apify Scheduler

Input

{
  "qualifiedInvoiceNumber": "T1000000000007",
  "transactions": [
    {
      "shopifyOrderName": "#1001",
      "shippingCountry": "US",
      "shippedAt": "2026-04-15",
      "amount": 100,
      "currency": "USD",
      "amountJpy": 15042,
      "exemptionReason": "export",
      "documents": ["customs_export_declaration", "ems_dispatch_note"],
      "retentionUntil": "2033-04-15",
      "evidenceDocsHashChain": "0ce5b547..."
    }
  ]
}

Field reference is in the Input tab. qualifiedInvoiceNumber is optional (omit if your business is below the ¥10M threshold and not registered).

Output

One dataset row per transaction. Each row contains:

Field	Type	Description
shopifyOrderName	string	Echoed back for matching
ok	boolean	Overall pass / fail
errors	string[]	Reasons the transaction fails the regime
warnings	string[]	Non-blocking issues (e.g. missing hash chain for audit defense)
documentSetOk	boolean	Carrier-document requirement satisfied?
documentSetMissing	string[]	Which document types are missing
issuerNumberValid	boolean | null	T-number checksum result (null when no T-number supplied)

Pricing

• Pay-Per-Result (PPE): $0.001 per transaction validated
• Free tier: First 5 runs/day per Apify account
• A typical 1,000-order year-end batch costs $1.00

No subscription, no minimum. You pay only for the transactions you actually validate.

Legal context

This Actor implements rules from:

• 消費税法 第7条1項 (export exemption)
• 消費税法施行令 第50条 (7-year retention)
• 国税庁通達 11-7-4 (acceptable carrier documents per amount bucket)
• 適格請求書等保存方式 (invoice system, T-number ISO 7064 MOD 9 checksum)

Validation logic is unit-tested against the published 国税庁 guidance. This Actor does not replace a 税理士 — it surfaces issues mechanically; final disposition is your accountant's call.

Known limits

• 国税庁通達 11-7-4 carrier-document list is the 2026 version; if 国税庁 issues updates, this Actor publishes a new version (see the Versions tab)
• Currency conversion (amountJpy) is your responsibility — supply it pre-converted (use the rate on shippedAt per 法人税基本通達 13の2-1-2)
• The Actor does not read your accounting system directly; supply the transactions as JSON

Roadmap

• v0.2: Direct Shopify Admin API integration (supply shop + token, skip the JSON marshaling)
• v0.3: PDF parsing for evidence docs (auto-extract document types from your customs paperwork)
• v0.4: 帳簿 (general ledger) cross-check against 消費税 申告書

Maintained by aulvem. Bug reports / feature requests via the Issues tab on the Actor page.

---

Developer notes

This Actor is part of a shared-modules monorepo. Validation logic lives in @ws/jp-vat-validator (30 unit tests). The Actor itself is thin glue between Apify SDK I/O and the library.

Local run (developers only):

cd apps/apify-jp-vat-validator
pnpm tsx src/main.ts

Uses Apify SDK in local mode; expects an INPUT.json in the configured KV store. See https://docs.apify.com/sdk/js/docs/guides/local-development.

Deploy is handled via apify-cli push from the maintainer's environment — pre-push sanity checks live in ../../docs/apify-actor-sanity-check.md.