Calculate Tax

Calculate income tax, corporate tax, or withholding tax for a given country and amount.

POST https://afrotools.com/api/tax

Authentication required. Pass your API key via x-api-key header. Learn more

Request Body

Send a JSON body with the following parameters:

Parameter	Type	Description
country required	string	ISO 3166-1 alpha-2 country code (e.g., `NG`, `KE`, `ZA`).
amount required	number	The monetary amount in the country's local currency.
type required	string	Tax type: `income`, `corporate`, `withholding`, or `capital_gains`.
period optional	string	Pay period: `monthly` (default), `annual`, `weekly`, or `biweekly`.
mode optional	string	Calculation mode: `gross_to_net` (default) or `net_to_gross`.
include_pension optional	boolean	Include pension/social security deductions. Default: `true`.
tax_year optional	string	Tax year (e.g., `2026`). Defaults to current year.

Response Fields

Field	Type	Description
country	string	ISO country code.
currency	string	ISO currency code.
gross_amount	number	Gross salary/amount before tax.
tax_amount	number	Total tax calculated.
pension	number	Pension/social security deduction (if applicable).
net_amount	number	Net amount after tax and deductions.
effective_rate	number	Effective tax rate as a percentage.
brackets	array	Tax brackets applied with from/to ranges and rates.
type	string	Tax type that was calculated.
period	string	Pay period used.
tax_year	string	Tax year applied.

Error Responses

Status	Code	Description
400	invalid_country	The country code is not supported.
400	invalid_amount	The amount must be a positive number.
400	invalid_tax_type	The tax type is not supported for this country.
401	missing_api_key	No API key was provided.
429	rate_limit_exceeded	Rate limit exceeded for your plan.

Request Examples

curl -X POST https://afrotools.com/api/tax \
  -H "x-api-key: afro_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "country": "NG",
    "amount": 500000,
    "type": "income",
    "period": "monthly"
  }'

const res = await fetch("https://afrotools.com/api/tax", {
  method: "POST",
  headers: {
    "x-api-key": "afro_live_your_key_here",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    country: "NG",
    amount: 500000,
    type: "income",
    period: "monthly"
  })
});
const data = await res.json();
console.log(data);

import requests

resp = requests.post(
    "https://afrotools.com/api/tax",
    headers={"x-api-key": "afro_live_your_key_here"},
    json={
        "country": "NG",
        "amount": 500000,
        "type": "income",
        "period": "monthly"
    }
)
data = resp.json()
print(data)

const axios = require("axios");

const { data } = await axios.post(
  "https://afrotools.com/api/tax",
  {
    country: "NG",
    amount: 500000,
    type: "income",
    period: "monthly"
  },
  {
    headers: { "x-api-key": "afro_live_your_key_here" }
  }
);
console.log(data);

$payload = json_encode([
    "country" => "NG",
    "amount" => 500000,
    "type" => "income",
    "period" => "monthly"
]);

$ch = curl_init("https://afrotools.com/api/tax");
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "x-api-key: afro_live_your_key_here",
    "Content-Type: application/json"
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);
$data = json_decode($response, true);
print_r($data);

Response (200 OK)

{
  "success": true,
  "data": {
    "country": "NG",
    "currency": "NGN",
    "gross_amount": 500000,
    "tax_amount": 78400,
    "pension": 40000,
    "net_amount": 381600,
    "effective_rate": 15.68,
    "type": "income",
    "period": "monthly",
    "mode": "gross_to_net",
    "brackets": [
      { "from": 0, "to": 300000, "rate": 7, "tax": 21000 },
      { "from": 300001, "to": 600000, "rate": 11, "tax": 22000 },
      { "from": 600001, "to": 1100000, "rate": 15, "tax": 0 },
      { "from": 1100001, "to": 1600000, "rate": 19, "tax": 0 },
      { "from": 1600001, "to": 3200000, "rate": 21, "tax": 0 },
      { "from": 3200001, "to": null, "rate": 24, "tax": 0 }
    ],
    "tax_year": "2026",
    "include_pension": true
  }
}

Error Response (400)

{
  "success": false,
  "error": {
    "code": "invalid_country",
    "message": "Country code 'XX' is not supported.",
    "docs": "https://afrotools.com/docs/api/tax/countries.html"
  }
}