API reference / Tax

Income tax calculator

Old/new regime, slabs, §87A, surcharge, cess.

POST/v1/tax/income
Authentication
Bearer token
Scope
tax:calc

Before you integrate

  • Surcharge marginal relief is not applied, so results just above a surcharge threshold come out slightly high.

Request body

FieldTypeRequiredDescription
regimestringYesold or new.
gross_income_minorintegerYesGross yearly income in paise; 0 or more.
salariedbooleanNoTrue to apply the standard deduction for salaried people. Defaults to false.
deductions_minorintegerNoChapter VI-A deductions such as 80C in paise. Used only under the old regime; ignored under the new one.

Sample code

Set your key in the GRAPPI_API_KEY environment variable. Sample values are placeholders.

curl -sS -X POST 'https://grappi.ai/v1/tax/income' \
  -H "Authorization: Bearer $GRAPPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "regime": "new",
  "gross_income_minor": 120000000,
  "salaried": true
}'

Sample response

{
  "request_id": "req_01HZY3K8M2",
  "result": {
    "regime": "new",
    "taxable_income_minor": 112500000,
    "base_tax_minor": 6875000,
    "rebate_87a_minor": 0,
    "surcharge_minor": 0,
    "cess_minor": 275000,
    "total_tax_minor": 7150000
  }
}

Response fields

FieldTypeDescription
regimestringThe regime used.
taxable_income_minorintegerIncome after deductions, in paise.
base_tax_minorintegerTax on the slabs before rebate, in paise.
rebate_87a_minorintegerSection 87A rebate in paise.
surcharge_minorintegerSurcharge in paise.
cess_minorintegerHealth and education cess in paise.
total_tax_minorintegerTotal tax payable in paise.

Errors

Every failure has the same shape. A call that fails on our side or at the data source is refunded to your wallet; a "no record found" answer is charged. See the error reference.