GST Tax Rates API

The GST Accelerator API is a condition-aware compliance engine that returns the exact applicable GST rate for any Indian good or service â€” including CGST, SGST, IGST, and Compensation Cess breakdowns â€” with a full CBIC notification audit trail.

Unlike legacy APIs that require you to call separate endpoints for HSN search, SAC search, and rate lookup, our engine does it all in a single POST request.

âœ“ CBIC-sourced data âœ“ Condition-aware engine âœ“ AI Agent / MCP ready âœ“ Updated Sept 2025

What makes us different

Products like footwear below â‚¹1,000 and garments below â‚¹1,000 have conditional GST rates. Every other API returns all possible rates and leaves it to you. We evaluate the condition against your transaction and return exactly one correct rate.

Base URL

https://gstaccelerator.in

Version

"api_version": "v1"
"data_source": "CBIC 09/2025-CT(Rate)"
"effective_from": "2025-09-22"

Quickstart

Get your first GST rate in under 60 seconds.

Create an account â€” Sign up with Google, GitHub, or email magic link on the Developer Dashboard.
Generate an API key â€” From your dashboard, click "Generate New Key". Copy it immediately â€” it will not be shown again.
Make your first request â€” Pass your key in the X-API-Key header. Try the cURL example on the right.
Parse the response â€” Use tax_rates.cgst, tax_rates.sgst, and applicable_rate in your invoice logic.

cURL â€” First Request

curl -X POST https://gstaccelerator.in/api/v1/lookup \
  -H "X-API-Key: gsta_live_*******************" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "laptop"
  }'

Response

[{
  "hsn_code": "8471",
  "description": "Portable automatic data processing machines",
  "tax_rates": {
    "igst": 18.0,
    "cgst": 9.0,
    "sgst": 9.0,
    "cess": 0.0
  },
  "applicable_rate": {
    "intrastate": "CGST 9.0% + SGST 9.0% = 18.0%",
    "interstate": "IGST 18.0%"
  },
  "notification_ref": "09/2025-CT(Rate)",
  "confidence": 0.95,
  "needs_review": false
}]

Authentication

All API requests require an API key passed in the X-API-Key HTTP request header. There are no session cookies or OAuth flows required for API access.

Generating a Key

Visit the Developer Dashboard, sign in with your preferred method, and click "Generate New Key". The full key is only shown once â€” store it in your environment variables immediately.

Keep your key secret

Never expose your API key in client-side JavaScript, public repos, or build logs. If compromised, immediately revoke it from the dashboard and generate a new one.

Header

X-API-Key: gsta_live_*******************

401 â€” Unauthorized

{
  "detail": "Invalid or revoked API key."
}

Health Check

GET /api/v1/health

Check the uptime and version of the API.

Response (200 OK)

{
  "status": "ok",
  "version": "1.0.0",
  "uptime": 3600.5
}

Database Meta

GET /api/v1/meta

Returns the total number of indexed HSN and SAC codes, and the CBIC notification source version.

Response (200 OK)

{
  "total_hsn": 12054,
  "total_sac": 845,
  "last_updated": "2025-06-01",
  "source": "GST Council Notification 09/2025-CT(Rate)"
}

Lookup GST Rate

POST /api/v1/lookup

The primary endpoint. Searches the CBIC Master Database for HSN/SAC codes matching your description, evaluates applicable conditions, and returns the exact GST rate for your transaction context.

Request Body

Field	Type	Description
description*	string	Natural language name of the good or service. e.g. `"cotton shirt"`, `"AC repair service"`
sale_value_inr	float	Transaction value in INR. Required to resolve price-threshold conditions (e.g. footwear < â‚¹1,000 = 5%, â‰¥ â‚¹1,000 = 12%).
branded	boolean	`true` if the product is pre-packaged and labelled (branded). Affects cereal, flour, pulses etc. Defaults to `false`.
b2b	boolean	`true` if buyer is a GST-registered business. Affects supply to SEZ, specific goods-transport services, etc.
supply_type	enum	`"intrastate"` or `"interstate"`. Controls the formatting of the `applicable_rate` string in the response. Defaults to `"intrastate"`.

cURL

curl -X POST https://gstaccelerator.in/api/v1/lookup \
  -H "X-API-Key: gsta_live_******************" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "split AC unit",
    "supply_type": "intrastate",
    "branded": true
  }'

Python

import requests

session = requests.Session()
session.headers["X-API-Key"] = "gsta_live_******************"

r = session.post(
    "https://gstaccelerator.in/api/v1/lookup",
    json={
        "description": "split AC unit",
        "supply_type": "intrastate",
        "branded": True,
    }
)
result = r.json()[0]
print(result["tax_rates"]["igst"])  # â†’ 18.0
print(result["applicable_rate"]["intrastate"])  # â†’ "CGST 9.0% + SGST 9.0%"

JavaScript (fetch)

const res = await fetch("https://gstaccelerator.in/api/v1/lookup", {
  method: "POST",
  headers: {
    "X-API-Key": "gsta_live_******************",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    description: "split AC unit",
    supply_type: "intrastate",
    branded: true,
  }),
});
const [result] = await res.json();
console.log(result.tax_rates.igst); // 18.0

Response (200 OK)

[
  {
    "hsn_code": "84151010",
    "description": "Air conditioning machines, split system",
    "tax_rates": {
      "igst": 18.0, "cgst": 9.0,
      "sgst": 9.0, "cess": 0.0,
      "total_intrastate": 18.0
    },
    "applicable_rate": {
      "intrastate": "CGST 9.0% + SGST 9.0% = 18.0%",
      "interstate": "IGST 18.0%"
    },
    "condition_applied": null,
    "condition_warning": null,
    "confidence": 0.9,
    "notification_ref": "09/2025-CT(Rate)",
    "needs_review": false
  }
]

Lookup GST Rate (GET)

GET /api/v1/lookup

Search for GST rates via query parameters. Identical behavior to the POST version, but useful for caching and simple integrations.

Query Parameters

Field	Type	Description
q*	string	The description keyword (e.g. `?q=cotton+shirt`)

cURL

curl -X GET "https://gstaccelerator.in/api/v1/lookup?q=cotton%20shirt"   -H "X-API-Key: gsta_live_***"

Autocomplete

GET /api/v1/autocomplete

Get fast typeahead suggestions for HSN descriptions based on a partial query. Returns up to 10 lightweight results.

Query Parameters

Field	Type	Description
q*	string	Partial query (e.g. `?q=batt`)

Response (200 OK)

[
  {
    "hsn_code": "8506",
    "hsn_description": "Primary cells and primary batteries"
  }
]

Lookup exact HSN code

GET /api/v1/hsn/{code}

Fetch the exact GST rate object for a specific 4-digit, 6-digit, or 8-digit HSN code.

cURL

curl -X GET "https://gstaccelerator.in/api/v1/hsn/8415"   -H "X-API-Key: gsta_live_***"

Lookup exact SAC code

GET /api/v1/sac/{code}

Fetch the exact GST rate object for a specific SAC code (services).

cURL

curl -X GET "https://gstaccelerator.in/api/v1/sac/9983"   -H "X-API-Key: gsta_live_***"

Get GST Rate by HSN

GET /api/v1/gst-rate

A convenient query-parameter based endpoint to get the GST rate for a given HSN code.

Query Parameters

Field	Type	Description
hsn*	string	The exact HSN code

cURL

curl -X GET "https://gstaccelerator.in/api/v1/gst-rate?hsn=8517"   -H "X-API-Key: gsta_live_***"

Bulk Lookup

POST /api/v1/bulk

Look up multiple HSN or SAC codes in a single request. Max 100 codes per request.

Request Body

[
  "8415",
  "85171300",
  "9983"
]

Condition Resolver

This is the defining feature of GST Accelerator. The CBIC notification database contains hundreds of conditional rate rules that most APIs ignore entirely.

Our engine parses these rules and evaluates them against the context you provide in your request. Examples of conditions we resolve:

Footwear below â‚¹1,000 â†’ 5%, at or above â†’ 12%
Garments below â‚¹1,000 â†’ 5%, at or above â†’ 12%
Cereals/flour pre-packaged & labelled â†’ 5%, loose â†’ 0%
Construction services (B2C affordable housing) â†’ 1%

Reading the response fields

condition_appliedDescribes which condition was found and whether it was resolved (PASSED/FAILED) against your inputs.

condition_warningNon-null when a condition exists but couldn't be resolved because a required input (e.g. sale_value_inr) was missing.

needs_reviewSet to true when the engine cannot confidently resolve the applicable rate and human verification is advised.

With condition â€” garment â‚¹1,500

// Request
{
  "description": "cotton shirt",
  "sale_value_inr": 1500.00,
  "supply_type": "intrastate"
}

// Condition resolved â†’ 12%
{
  "tax_rates": { "igst": 12.0, "cgst": 6.0, "sgst": 6.0 },
  "condition_applied": "Price â‰¥ â‚¹1,000 threshold: PASSED â€” â‚¹1,500 > â‚¹1,000",
  "condition_warning": null,
  "needs_review": false
}

Without value â€” warning issued

// Request â€” no sale_value_inr
{ "description": "cotton shirt" }

// Cannot resolve â€” warning added
{
  "condition_applied": null,
  "condition_warning": "Price threshold condition exists. Provide sale_value_inr to resolve.",
  "needs_review": true
}

Supply Types

Pass supply_type to get the correct rate formatted for your transaction type. This does not change the underlying IGST/CGST/SGST values â€” it only formats the applicable_rate string in the response.

Value	Meaning
intrastate	Supplier and buyer in the same state. Rate = CGST + SGST. Default.
interstate	Supplier and buyer in different states. Rate = IGST only.

Intrastate vs Interstate

// applicable_rate when intrastate
"applicable_rate": {
  "intrastate": "CGST 9.0% + SGST 9.0% = 18.0%",
  "interstate": "IGST 18.0%"
}

// Invoice GST calculation â€” intrastate
invoice_value = 25000
cgst = (invoice_value Ã— 9) / 100  # â‚¹2,250
sgst = (invoice_value Ã— 9) / 100  # â‚¹2,250

// Invoice GST calculation â€” interstate
igst = (invoice_value Ã— 18) / 100 # â‚¹4,500

Response Fields

All successful responses return a JSON array, sorted by confidence score (highest first). Up to 50 results are returned.

hsn_codeThe HSN (goods) or SAC (services) code matched from the CBIC Master Database.

descriptionOfficial CBIC description for this code.

tax_rates.igstIntegrated GST rate (%). Used for interstate supply.

tax_rates.cgstCentral GST rate (%). Used with SGST for intrastate supply.

tax_rates.sgstState GST rate (%). Equal to CGST for intrastate supply.

tax_rates.cessCompensation Cess rate, if applicable. Common for luxury and sin goods.

applicable_rateHuman-readable rate strings for both intrastate and interstate supply.

condition_appliedDescription of the condition evaluated and the result of evaluation.

condition_warningWarning message when a condition exists but could not be resolved due to missing input.

confidenceMatch confidence score from 0.0 to 1.0. Higher is better.

notification_refCBIC notification reference for audit trail (e.g. "09/2025-CT(Rate)").

needs_reviewtrue when human verification is recommended before using the rate.

Full Response Object

{
  "hsn_code": "6205",
  "description": "Men's or boys' shirts",
  "tax_rates": {
    "igst": 12.0,
    "cgst": 6.0,
    "sgst": 6.0,
    "utgst": 6.0,
    "cess": 0.0,
    "total_intrastate": 12.0,
    "total_interstate": 12.0
  },
  "applicable_rate": {
    "intrastate": "CGST 6.0% + SGST 6.0% = 12.0%",
    "interstate": "IGST 12.0%",
    "recommended": null
  },
  "condition_applied": "Price â‰¥ â‚¹1,000: PASSED â€” â‚¹1,500 > â‚¹1,000",
  "condition_warning": null,
  "confidence": 0.9,
  "notification_ref": "09/2025-CT(Rate)",
  "needs_review": false
}

Error Codes

The API uses standard HTTP status codes. All error responses include a detail field with a human-readable message.

400Bad Request â€” A required field is missing or a value is invalid. Check the detail field for specifics.

401Unauthorized â€” The X-API-Key header is missing, the key is invalid, or it has been revoked.

422Unprocessable Entity â€” The request body is malformed JSON or a field has the wrong type.

429Too Many Requests â€” Your plan's monthly call limit has been reached. Upgrade on the dashboard.

500Internal Server Error â€” Something went wrong on our end. Please retry, and contact support if the issue persists.

Error Format

{
  "detail": "Invalid or revoked API key."
}

Validation Error (422)

{
  "detail": [
    {
      "loc": ["body", "description"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}

Rate Limits

Limits apply per API key per calendar month. Requests that exceed your plan's quota receive a 429 response.

Plan	Monthly Quota	Overage
Free	100 calls	Blocked
Developer	5,000 calls	â‚¹0.10 / call
Pro	50,000 calls	â‚¹0.08 / call
Business	Unlimited	â€”

Need more calls?

Upgrade your plan from the Developer Dashboard or contact hello@gstaccelerator.in for custom enterprise quotas.