HSN Code Lookup AI Agent / LLM

# HSN Code Lookup API — Way2API®

- **Endpoint:** `POST https://app.way2api.com/api/v1/gst/hsn-code`
- **Auth:** `Authorization: Bearer YOUR_API_KEY` (or `X-API-Key: YOUR_API_KEY`)
- **Content-Type:** `application/json`
- **Category:** Business
- **Availability:** Available in India
- **Docs:** https://app.way2api.com/documentation/hsn-code-lookup

## What it does

HSN Code Lookup API — Validate an HSN code (goods) or SAC code (services) and get what the code actually covers: its official tariff description, the chapter it sits under, the applicable GST rate, the rate-revision history, the cess note, and the date each revision took effect. Accepts 2, 4, 6 or 8-digit HSN codes and 6-digit SAC codes, and reports which schedule the code came from in code_type. Rates come back twice — in the schedule's own notation in gst_rate ("5/12/18") and as a numeric list in gst_rate_percent ([5, 12, 18]) so they can be compared without parsing — and every effective date is returned as an ISO date, most recent revision first. Use it to check an HSN code and its GST rate before raising an invoice, validate the codes a supplier put on an incoming purchase invoice, and keep a product or service catalogue tax-correct.

## Request body (application/json)

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `hsn_code` | string | yes | HSN code for goods (2, 4, 6 or 8 digits) or SAC code for services (6 digits, beginning 99). Digits only. |

## Example request

```bash
curl -X POST https://app.way2api.com/api/v1/gst/hsn-code \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"hsn_code":"998319"}'
```

## Success response — 200

```json
{
    "status": "SUCCESS",
    "status_code": 200,
    "charged": true,
    "success": true,
    "message": "",
    "message_code": "OK",
    "order_id": "W2A1739512345abcdef01",
    "data": {
        "order_id": "W2A1739512345abcdef01",
        "result": {
            "hsn_code": "998319",
            "code_type": "SAC",
            "description": "OTHER INFORMATION TECHNOLOGY SERVICES N.E.C",
            "chapter_number": 99,
            "chapter_name": "Services",
            "gst_rate": "5/12/18",
            "gst_rate_percent": [
                5,
                12,
                18
            ],
            "rate_revision": "12% 5% 18%",
            "effective_date": "2019-10-01",
            "effective_dates": [
                "2019-10-01",
                "2017-07-01"
            ],
            "cess": "Nil Provided that Director (Sports), Ministry of Youth Affairs and Sports certifies that the services are directly or indirectly related to any of the events under FIFA U-17 Women's World Cup 2020."
        }
    }
}
```

## Error response — 422

```json
{
    "status": "SUCCESS",
    "status_code": 422,
    "charged": true,
    "success": false,
    "message": "No HSN or SAC record was found for the code provided.",
    "message_code": "NO_RECORD_FOUND",
    "order_id": "W2A1739512345abcdef01",
    "data": {
        "order_id": "W2A1739512345abcdef01",
        "error_code": "NO_RECORD",
        "result": {
            "hsn_code": "9999999",
            "code_type": "",
            "description": "",
            "chapter_number": 0,
            "chapter_name": "",
            "gst_rate": "",
            "gst_rate_percent": [],
            "rate_revision": "",
            "effective_date": null,
            "effective_dates": [],
            "cess": ""
        }
    }
}
```

## Integration rules

- Every response is JSON carrying `status`, `status_code`, `charged`, `success`, `message`, `message_code` and (once a call reaches the provider) `order_id`. The verification payload is under `data.result`.
- `charged` (boolean) is the authority on billing. Do NOT infer it from the HTTP status: `422` is returned both for input we rejected (not charged) and for a lookup the provider ran and billed us for that returned a negative result (charged).
- `message_code` is a fixed vocabulary — branch on it instead of parsing `message`. Values: `OK`, `ACCEPTED`, `PROVIDER_NO_RESPONSE`, `VERIFICATION_FAILED`, `NO_RECORD_FOUND`, `INVALID_INPUT`, `REQUEST_FAILED`, `MISSING_API_KEY`, `INVALID_API_KEY`, `INSUFFICIENT_BALANCE`, `NO_API_ACCESS`, `NOT_FOUND`, `RATE_LIMITED`, `INTERNAL_ERROR`, `PROVIDER_UNAVAILABLE`.
- `success` reports the verification outcome; `status` reports the ORDER lifecycle (`SUCCESS`/`PENDING`/`FAILED`). They differ on a charged negative result: the order completed and was billed while the verification did not pass.
- A failed verification is still a successful HTTP call — the outcome lives in the response body, so do not treat `200` as "verified".
- Status codes: `200` result returned, `202` pending or provider did not respond (both charged — quote the `order_id`), `401` missing/invalid key, `402` insufficient balance, `403` no access to this service, `422` see `charged`, `429` rate limited (honour the `Retry-After` header), `503` temporarily unavailable.
- Rate limits are per API key, per service, on a 1-minute sliding window.
- Load the API key from an environment variable or secret store. Never hard-code it, never commit it, and never ship it in client-side code — calls must be made from your backend.