Calculate VAT

Add VAT to a net amount or extract the VAT component from a gross amount for any African country.

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

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 local currency. Must be a positive number.
mode required	string	Calculation mode: `add` (add VAT to net amount) or `extract` (extract VAT from gross amount).
rate_type optional	string	VAT rate category: `standard` (default), `reduced`, or `zero`.
category optional	string	Product category for rate lookup: `standard`, `food_basic`, `medical`, `education`, `digital`, `export`.

Response Fields

Field	Type	Description
country	string	ISO country code.
country_name	string	Full country name.
currency	string	ISO currency code.
mode	string	Calculation mode used (`add` or `extract`).
net_amount	number	Amount before VAT.
vat_rate	number	VAT rate applied (%).
vat_amount	number	VAT component.
gross_amount	number	Amount including VAT.
rate_type	string	Rate category applied.
updated	string	Date the VAT rate was last updated.

Error Responses

Status	Code	Description
400	INVALID_COUNTRY	The country code is not supported.
400	INVALID_SALARY	The amount must be a positive number.
400	MISSING_REQUIRED_FIELD	A required field (country, amount, or mode) is missing.
401	INVALID_API_KEY	No valid API key was provided.
429	RATE_LIMIT_EXCEEDED	Rate limit exceeded for your plan.

Request Examples

curl -X POST https://afrotools.com/api/vat \
  -H "x-api-key: afro_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "country": "NG",
    "amount": 100000,
    "mode": "add"
  }'

const res = await fetch("https://afrotools.com/api/vat", {
  method: "POST",
  headers: {
    "x-api-key": "afro_live_your_key_here",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    country: "NG",
    amount: 100000,
    mode: "add"
  })
});
const data = await res.json();
console.log(`VAT: ${data.data.vat_amount}`);

import requests

resp = requests.post(
    "https://afrotools.com/api/vat",
    headers={"x-api-key": "afro_live_your_key_here"},
    json={
        "country": "NG",
        "amount": 100000,
        "mode": "add"
    }
)
data = resp.json()
print(f"VAT: {data['data']['vat_amount']} NGN")

const axios = require("axios");

const { data } = await axios.post(
  "https://afrotools.com/api/vat",
  {
    country: "NG",
    amount: 100000,
    mode: "add"
  },
  {
    headers: { "x-api-key": "afro_live_your_key_here" }
  }
);
console.log(`VAT: ${data.data.vat_amount} NGN`);

$payload = json_encode([
    "country" => "NG",
    "amount" => 100000,
    "mode" => "add"
]);

$ch = curl_init("https://afrotools.com/api/vat");
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);
echo "VAT: " . $data["data"]["vat_amount"] . " NGN";

Response — Add Mode (200 OK)

{
  "success": true,
  "data": {
    "country": "NG",
    "country_name": "Nigeria",
    "currency": "NGN",
    "mode": "add",
    "net_amount": 100000,
    "vat_rate": 7.5,
    "vat_amount": 7500,
    "gross_amount": 107500,
    "rate_type": "standard",
    "updated": "2026-01-01"
  }
}

Response — Extract Mode

# Extract VAT from 107,500 NGN
{
  "success": true,
  "data": {
    "country": "NG",
    "country_name": "Nigeria",
    "currency": "NGN",
    "mode": "extract",
    "net_amount": 100000,
    "vat_rate": 7.5,
    "vat_amount": 7500,
    "gross_amount": 107500,
    "rate_type": "standard",
    "updated": "2026-01-01"
  }
}

Error Response (400)

{
  "success": false,
  "error": {
    "code": "MISSING_REQUIRED_FIELD",
    "message": "The 'mode' field is required. Use 'add' or 'extract'.",
    "docs": "https://afrotools.com/docs/api/vat/calculate.html"
  }
}