# Japan Withholding Tax (源泉徴収) Calculator for Freelance Fees (`autoworks-jp/japan-withholding-tax-calculator`) Actor Calculate Japanese withholding income tax (源泉徴収税額) on fees paid to freelancers: 10.21% / 20.42% over ¥1M, judicial scrivener and sales-agent deductions, tax-exclusive base. Verifies the amount stated on invoices. Pure computation. - **URL**: https://apify.com/autoworks-jp/japan-withholding-tax-calculator.md - **Developed by:** [AutoWorks JP](https://apify.com/autoworks-jp) (community) - **Categories:** Business, Automation, Developer tools - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing from $3.00 / 1,000 payments This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events. Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event ## What's an Apify Actor? An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes. In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours, and optionally produces a well-defined JSON output, datasets with results, or files in key-value store. In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server. Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md. ## How to integrate an Actor? If asked about integration, you help developers integrate Actors into their projects. You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready. Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run. For examples already wired to this Actor's own input schema, see the [API](#api) section below. Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`). # README Calculate **Japanese withholding income tax (源泉徴収税額)** on fees you pay to freelancers and sole proprietors — in bulk, deterministically, and check whether the amount written on their invoice is right. Typical mistakes this Actor catches: | Mistake | Example | | --- | --- | | Forgot the 2.1% surtax | Withheld 10% instead of **10.21%** | | Wrong base | Computed on the tax-inclusive amount although consumption tax is shown separately | | Missed the ¥1M tier | Applied 10.21% to the whole amount instead of **20.42% on the part over ¥1,000,000** | | Missed a deduction | Judicial scrivener (¥10,000 per payment) or sales agent (¥120,000 per month) | | Withheld from a company | Payments to corporations are generally not subject to this withholding | Pure computation: no scraping, no API keys, no personal data required. Only amounts and a category. ### Supported categories | `category` | Covers | Formula | | --- | --- | --- | | `standard` (default) | Writing, design, lectures, translation, lawyers, tax accountants, etc. | ≤ ¥1M: × 10.21% / over ¥1M: (amount − 1,000,000) × 20.42% + 102,100 | | `judicial_scrivener` | 司法書士・土地家屋調査士・海事代理士 | (amount − 10,000) × 10.21% | | `sales_agent` | 外交員・集金人・検針人 | (amount − 120,000) × 10.21% (monthly) | Yen fractions are rounded down. The 10.21% / 20.42% rates already include the 2.1% surtax; from January 2027 the surtax is split into 防衛特別所得税 1% + 復興特別所得税 1.1%, so the **combined rate does not change**. ### Input ```json { "payments": [ { "id": "PAY-001", "category": "standard", "fee": 100000, "consumptionTax": 10000, "consumptionTaxSeparated": true, "statedWithholding": 10210 }, { "id": "PAY-002", "fee": 1500000, "consumptionTax": 150000 }, { "id": "PAY-003", "category": "judicial_scrivener", "fee": 50000, "consumptionTax": 5000 } ] } ``` | Field | Notes | | --- | --- | | `fee` | Fee before consumption tax. Numbers or strings like `"１００,０００円"` | | `consumptionTax` | Optional, default 0 | | `consumptionTaxSeparated` | `true` (default) if the invoice shows fee and consumption tax separately → tax-exclusive base | | `payeeType` | `individual` (default) or `corporation` | | `statedWithholding` | Optional. The amount written on the invoice, to verify | ### Output One dataset item per payment: ```json { "id": "PAY-001", "status": "MATCH", "category": "standard", "taxBase": 100000, "withholdingTax": 10210, "netPayment": 99790, "formula": "100,000 × 10.21%", "statedWithholding": 10210, "issues": [] } ``` `status` is `CALCULATED`, `MATCH`, `MISMATCH` or `INVALID`. `netPayment` is the amount to transfer (fee + consumption tax − withholding). A summary is saved to the key-value store as `SUMMARY`. ### Pair it with [Japan Qualified Invoice (インボイス) Compliance Checker](https://apify.com/autoworks-jp/japan-qualified-invoice-compliance-checker) — validate the invoice itself, then calculate the withholding. ### Limitations - Covers fees under 所得税法 Article 204 for the three categories above only. Salaries, bonuses, retirement pay, non-resident payments and hostess fees are not supported. - Assumes one payment per month for `sales_agent`. - This is a calculation aid, not tax advice. Check special cases with a tax professional. *** #### 日本語概要 個人（フリーランス・個人事業主）へ支払う報酬・料金の源泉徴収税額を一括計算し、請求書に記載された金額が正しいかを検証します。100万円超の部分の20.42%、司法書士等の1万円控除、外交員の12万円控除、消費税を区分記載した場合の税抜計算、法人への支払（原則対象外）に対応しています。2027年1月からの防衛特別所得税の導入後も合計税率は変わりません。金額と区分だけで計算でき、個人情報の入力は不要です。 詳しい解説記事（Qiita）: [インボイスの「端数処理ミス」と源泉徴収の「10%計算ミス」をPythonで一括検出する](https://qiita.com/autoworks2/items/b208f61c0fa479740cb0) # Actor input Schema ## `payments` (type: `array`): List of fee payments. Fields: id, category (standard | judicial_scrivener | sales_agent), payeeType (individual | corporation), fee, consumptionTax, consumptionTaxSeparated, statedWithholding. ## Actor input object example ```json { "payments": [ { "id": "PAY-001", "category": "standard", "fee": 100000, "consumptionTax": 10000, "consumptionTaxSeparated": true, "statedWithholding": 10210 }, { "id": "PAY-002", "category": "standard", "fee": 1500000, "consumptionTax": 150000 }, { "id": "PAY-003", "category": "judicial_scrivener", "fee": 50000, "consumptionTax": 5000 } ] } ``` # Actor output Schema ## `results` (type: `string`): No description # API You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup. ## JavaScript example ```javascript import { ApifyClient } from 'apify-client'; // Initialize the ApifyClient with your Apify API token // Replace the '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "payments": [ { "id": "PAY-001", "category": "standard", "fee": 100000, "consumptionTax": 10000, "consumptionTaxSeparated": true, "statedWithholding": 10210 }, { "id": "PAY-002", "category": "standard", "fee": 1500000, "consumptionTax": 150000 }, { "id": "PAY-003", "category": "judicial_scrivener", "fee": 50000, "consumptionTax": 5000 } ] }; // Run the Actor and wait for it to finish const run = await client.actor("autoworks-jp/japan-withholding-tax-calculator").call(input); // Fetch and print Actor results from the run's dataset (if any) console.log('Results from dataset'); console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`); const { items } = await client.dataset(run.defaultDatasetId).listItems(); items.forEach((item) => { console.dir(item); }); // 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs ``` ## Python example ```python from apify_client import ApifyClient # Initialize the ApifyClient with your Apify API token # Replace '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "payments": [ { "id": "PAY-001", "category": "standard", "fee": 100000, "consumptionTax": 10000, "consumptionTaxSeparated": True, "statedWithholding": 10210, }, { "id": "PAY-002", "category": "standard", "fee": 1500000, "consumptionTax": 150000, }, { "id": "PAY-003", "category": "judicial_scrivener", "fee": 50000, "consumptionTax": 5000, }, ] } # Run the Actor and wait for it to finish run = client.actor("autoworks-jp/japan-withholding-tax-calculator").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}") for item in client.dataset(run.default_dataset_id).iterate_items(): print(item) # 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{ "payments": [ { "id": "PAY-001", "category": "standard", "fee": 100000, "consumptionTax": 10000, "consumptionTaxSeparated": true, "statedWithholding": 10210 }, { "id": "PAY-002", "category": "standard", "fee": 1500000, "consumptionTax": 150000 }, { "id": "PAY-003", "category": "judicial_scrivener", "fee": 50000, "consumptionTax": 5000 } ] }' | apify call autoworks-jp/japan-withholding-tax-calculator --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "type": "http", "url": "https://mcp.apify.com/?tools=fetch-actor-details,autoworks-jp/japan-withholding-tax-calculator" } } } ``` The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer ` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations). ## OpenAPI specification Download the OpenAPI definition: https://api.apify.com/v2/actors/sW9dzuJXov4WcgDgc/builds/aDCUYapoynTn8tO27/openapi.json