DEV Community

Hemant Kumar Sharma
Hemant Kumar Sharma

Posted on

India GST Utilities API: Validate GSTINs, Calculate Tax & Look Up HSN/SAC Codes (Free)

#india #webdev #javascript #python

If you're building any Indian business application — billing software, e-commerce checkout, invoice generator, accounting tool — you've probably had to deal with this:

  • Writing GSTIN validation logic from scratch (and getting the checksum algorithm wrong)
  • Building a GST calculator that handles intra-state vs inter-state, inclusive vs exclusive
  • Maintaining a local database of 1000+ HSN and SAC codes

I got tired of doing this in every project, so I built a single API that handles all of it. It's free to use via RapidAPI.

Live API base URL: https://india-gst-utilities.p.rapidapi.com

What the API covers

Endpoint What it does
GET /gstin/validate Validates format + checksum, decodes state/PAN/entity
GET /gstin/details Decoded GSTIN breakdown + PAN holder type
GET /gst/calculate CGST/SGST/IGST split, inclusive & exclusive
GET /gst/rates All valid GST rates in India
GET /hsn/search Search HSN codes by keyword
GET /hsn/rate GST rate for a specific HSN code
GET /hsn/list Paginated full HSN list, filterable by rate
GET /sac/search Search SAC codes (services) by keyword
GET /sac/rate GST rate for a specific SAC code

Getting started

  1. Sign up at RapidAPI (free)
  2. Subscribe to India GST Utilities — the Basic plan is free (5 req/min)
  3. Copy your x-rapidapi-key from the dashboard

All examples below use the RapidAPI endpoint. Add these headers to every request:

x-rapidapi-key: YOUR_KEY_HERE
x-rapidapi-host: india-gst-utilities.p.rapidapi.com
Enter fullscreen mode Exit fullscreen mode

1. Validate a GSTIN

GSTIN has a specific structure: SS PPPPPPPPPP E Z C

  • SS = 2-digit state code
  • PPPPPPPPPPP = 10-char PAN number
  • E = entity registration number (1–9, A–Z)
  • Z = always Z
  • C = checksum digit (computed via a specific algorithm)

The API validates all of this and decodes the breakdown:

JavaScript (fetch)

const response = await fetch(
  'https://india-gst-utilities.p.rapidapi.com/gstin/validate?gstin=27AAPFU0939F1ZV',
  {
    headers: {
      'x-rapidapi-key': 'YOUR_KEY_HERE',
      'x-rapidapi-host': 'india-gst-utilities.p.rapidapi.com'
    }
  }
);
const data = await response.json();
console.log(data);
Enter fullscreen mode Exit fullscreen mode

Response:

{
  "valid": true,
  "gstin": "27AAPFU0939F1ZV",
  "breakdown": {
    "state_code": "27",
    "state_name": "Maharashtra",
    "pan": "AAPFU0939F",
    "entity_number": "1",
    "check_digit": "V"
  }
}
Enter fullscreen mode Exit fullscreen mode

Python (requests)

import requests

url = "https://india-gst-utilities.p.rapidapi.com/gstin/validate"
headers = {
    "x-rapidapi-key": "YOUR_KEY_HERE",
    "x-rapidapi-host": "india-gst-utilities.p.rapidapi.com"
}

response = requests.get(url, params={"gstin": "27AAPFU0939F1ZV"}, headers=headers)
data = response.json()

if data["valid"]:
    print(f"Valid GSTIN — {data['breakdown']['state_name']}, PAN: {data['breakdown']['pan']}")
else:
    print("Invalid GSTIN:", data.get("errors"))
Enter fullscreen mode Exit fullscreen mode

Invalid GSTIN response (wrong checksum):

{
  "valid": false,
  "gstin": "27AAPFU0939F1ZX",
  "errors": ["Invalid check digit: expected 'V', found 'X'"]
}
Enter fullscreen mode Exit fullscreen mode

2. Calculate GST

Handles both intra-state (CGST + SGST) and inter-state (IGST), and both tax-exclusive and tax-inclusive amounts.

JavaScript — intra-state, tax exclusive:

const response = await fetch(
  'https://india-gst-utilities.p.rapidapi.com/gst/calculate?amount=10000&rate=18&type=intra&inclusive=false',
  { headers: { 'x-rapidapi-key': 'YOUR_KEY', 'x-rapidapi-host': 'india-gst-utilities.p.rapidapi.com' } }
);
const tax = await response.json();
console.log(tax);
Enter fullscreen mode Exit fullscreen mode

Response:

{
  "base_amount": 10000,
  "gst_rate": 18,
  "transaction_type": "Intra-State (within same state)",
  "gst_inclusive": false,
  "total_gst": 1800,
  "total_amount": 11800,
  "cgst_rate": 9,
  "sgst_rate": 9,
  "cgst_amount": 900,
  "sgst_amount": 900
}
Enter fullscreen mode Exit fullscreen mode

Python — inter-state, tax inclusive (reverse calculation):

import requests

params = {
    "amount": 5000,   # MRP shown to customer
    "rate": 18,
    "type": "inter",
    "inclusive": "true"
}
headers = {
    "x-rapidapi-key": "YOUR_KEY_HERE",
    "x-rapidapi-host": "india-gst-utilities.p.rapidapi.com"
}

r = requests.get(
    "https://india-gst-utilities.p.rapidapi.com/gst/calculate",
    params=params, headers=headers
).json()

print(f"Base amount: ₹{r['base_amount']}")
print(f"IGST (18%): ₹{r['total_gst']}")
print(f"Total (MRP): ₹{r['total_amount']}")
Enter fullscreen mode Exit fullscreen mode

Response:

{
  "base_amount": 4237.29,
  "gst_rate": 18,
  "transaction_type": "Inter-State",
  "gst_inclusive": true,
  "total_gst": 762.71,
  "total_amount": 5000,
  "igst_rate": 18,
  "igst_amount": 762.71
}
Enter fullscreen mode Exit fullscreen mode

3. Search HSN Codes

HSN (Harmonized System of Nomenclature) codes classify goods. Every invoice in India must carry the correct HSN code and the API makes it easy to look them up.

JavaScript:

const response = await fetch(
  'https://india-gst-utilities.p.rapidapi.com/hsn/search?q=cotton&limit=5',
  { headers: { 'x-rapidapi-key': 'YOUR_KEY', 'x-rapidapi-host': 'india-gst-utilities.p.rapidapi.com' } }
);
const result = await response.json();
result.results.forEach(item => {
  console.log(`${item.code} — ${item.description} — GST: ${item.rate}%`);
});
Enter fullscreen mode Exit fullscreen mode

Response:

{
  "query": "cotton",
  "count": 3,
  "results": [
    { "code": "1512", "description": "Sunflower-seed, safflower or cotton-seed oil", "rate": 5 },
    { "code": "5201", "description": "Cotton, not carded or combed", "rate": 5 },
    { "code": "5208", "description": "Woven fabrics of cotton, 85% or more, up to 200 g/m2", "rate": 5 }
  ]
}
Enter fullscreen mode Exit fullscreen mode

Get the GST rate for a specific HSN code:

r = requests.get(
    "https://india-gst-utilities.p.rapidapi.com/hsn/rate",
    params={"code": "5201"},
    headers=headers
).json()

print(f"HSN {r['code']}: {r['description']}")
print(f"GST: {r['gst_rate']}% | CGST: {r['cgst_rate']}% | SGST: {r['sgst_rate']}% | IGST: {r['igst_rate']}%")
Enter fullscreen mode Exit fullscreen mode

Response:

{
  "code": "5201",
  "description": "Cotton, not carded or combed",
  "gst_rate": 5,
  "cgst_rate": 2.5,
  "sgst_rate": 2.5,
  "igst_rate": 5
}
Enter fullscreen mode Exit fullscreen mode

4. Search SAC Codes (Services)

SAC (Services Accounting Code) codes classify services — required on invoices from service providers, freelancers, consultants, etc.

Python:

r = requests.get(
    "https://india-gst-utilities.p.rapidapi.com/sac/search",
    params={"q": "education", "limit": 5},
    headers=headers
).json()

for item in r["results"]:
    print(f"SAC {item['code']}: {item['description']} — GST: {item['rate']}%")
Enter fullscreen mode Exit fullscreen mode

Response:

{
  "query": "education",
  "count": 3,
  "results": [
    { "code": "9992", "description": "Education services", "rate": 0 },
    { "code": "999210", "description": "Pre-primary education services", "rate": 0 },
    { "code": "999211", "description": "Primary education services", "rate": 0 }
  ]
}
Enter fullscreen mode Exit fullscreen mode

Real-world use cases

E-commerce checkout — auto-calculate CGST+SGST or IGST based on whether seller and buyer are in the same state:

async function calculateCheckoutTax(amount, sellerState, buyerState) {
  const type = sellerState === buyerState ? 'intra' : 'inter';
  const response = await fetch(
    `https://india-gst-utilities.p.rapidapi.com/gst/calculate?amount=${amount}&rate=18&type=${type}&inclusive=false`,
    { headers: { 'x-rapidapi-key': 'YOUR_KEY', 'x-rapidapi-host': 'india-gst-utilities.p.rapidapi.com' } }
  );
  return response.json();
}
Enter fullscreen mode Exit fullscreen mode

Invoice validator — check GSTIN before saving a vendor/customer record:

def validate_vendor_gstin(gstin: str) -> dict:
    r = requests.get(
        "https://india-gst-utilities.p.rapidapi.com/gstin/validate",
        params={"gstin": gstin},
        headers=headers
    ).json()
    if not r["valid"]:
        raise ValueError(f"Invalid GSTIN: {r.get('errors', [])}")
    return r["breakdown"]
Enter fullscreen mode Exit fullscreen mode

Tally/ERP integration — auto-fill HSN code and tax rate when a product is added:

async function getProductTaxDetails(productKeyword) {
  const search = await fetch(
    `https://india-gst-utilities.p.rapidapi.com/hsn/search?q=${productKeyword}&limit=1`,
    { headers: { 'x-rapidapi-key': 'YOUR_KEY', 'x-rapidapi-host': 'india-gst-utilities.p.rapidapi.com' } }
  ).then(r => r.json());

  if (!search.results.length) return null;
  const { code } = search.results[0];

  const rate = await fetch(
    `https://india-gst-utilities.p.rapidapi.com/hsn/rate?code=${code}`,
    { headers: { 'x-rapidapi-key': 'YOUR_KEY', 'x-rapidapi-host': 'india-gst-utilities.p.rapidapi.com' } }
  ).then(r => r.json());

  return { hsn_code: code, gst_rate: rate.gst_rate };
}
Enter fullscreen mode Exit fullscreen mode

Pricing

Plan Price Rate limit
Basic Free 5 req/min
Pro $9.99/month 30 req/min
Ultra $29.99/month 1,000 req/hour
MEGA $99.99/month 500 req/min

The free tier is more than enough for development and low-traffic apps.

Try it now

👉 India GST Utilities on RapidAPI — sign up, subscribe to the free Basic plan, and you get an API key instantly. No credit card required for the free tier.

If you find a missing HSN/SAC code or have a feature request, drop a comment below. Happy to add more endpoints — invoice number format validation, e-way bill utilities, or GST filing due dates are next on the list.

Top comments (0)