> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pazy.io/llms.txt
> Use this file to discover all available pages before exploring further.

# GST Taxes API

> List the GST tax rates configured for your organization

## Authentication

All requests require an API key in the request headers.

**Headers:**

```
Authorization: Api-Key YOUR_API_KEY
```

The permission required on your API key is **Tax** with the **Read** action enabled.

## Request

This endpoint takes no path parameters, query parameters, or body. Every GST tax configured for the organization is returned in a single response — there is no pagination.

<Info>
  GST taxes are configured per GSTIN entity, so an organization with multiple registered entities returns one entry per rate **per entity**. Use `entityGstin` to pick the rows belonging to the entity you're raising the transaction for.
</Info>

## Code Examples

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET https://api.pazy.io/v1.0/taxes/gst \
    -H "Authorization: Api-Key YOUR_API_KEY"
  ```

  ```javascript JavaScript (Fetch API) theme={null}
  const response = await fetch('https://api.pazy.io/v1.0/taxes/gst', {
    method: 'GET',
    headers: {
      Authorization: 'Api-Key YOUR_API_KEY'
    }
  });

  const result = await response.json();
  ```

  ```python Python (requests) theme={null}
  import requests

  url = "https://api.pazy.io/v1.0/taxes/gst"
  headers = {
      "Authorization": "Api-Key YOUR_API_KEY"
  }

  response = requests.get(url, headers=headers)
  result = response.json()
  ```
</CodeGroup>

## Success Response

**HTTP Status:** `200 OK`

**Response Fields:**

| Field                            | Type    | Description                                                                                      |
| -------------------------------- | ------- | ------------------------------------------------------------------------------------------------ |
| `ok`                             | boolean | Indicates whether the request was successful                                                     |
| `data.gstList`                   | array   | GST taxes configured for the organization                                                        |
| `data.gstList[].id`              | string  | Tax id. Pass this as `gstId` to the [Vendor Advance Creation](/apis/vendor-advance-creation) API |
| `data.gstList[].label`           | string  | Display name given to the tax in Pazy                                                            |
| `data.gstList[].description`     | string  | The GST component this tax represents — same value as `section`                                  |
| `data.gstList[].section`         | string  | GST component e.g. `IGST`, `CGST`, `SGST`                                                        |
| `data.gstList[].rate`            | number  | Tax value — a percentage when `rateType` is `PERCENTAGE`, an absolute amount when `ABSOLUTE`     |
| `data.gstList[].rateType`        | string  | How `rate` is applied: `PERCENTAGE` or `ABSOLUTE`                                                |
| `data.gstList[].dateCreated`     | string  | ISO 8601 timestamp of when the tax was created                                                   |
| `data.gstList[].entityGstin`     | string  | GSTIN of the organization entity this tax belongs to                                             |
| `data.gstList[].entityGstinName` | string  | Name of that organization entity                                                                 |

### Response Example

```json theme={null}
{
  "ok": true,
  "data": {
    "gstList": [
      {
        "id": "4170",
        "label": "New GST Rate",
        "description": "IGST",
        "section": "IGST",
        "rate": 18,
        "rateType": "PERCENTAGE",
        "dateCreated": "2026-04-08T03:12:44.446Z",
        "entityGstin": "29AAJCM3528P1ZR",
        "entityGstinName": "MDP Coffee House"
      },
      {
        "id": "4171",
        "label": "GST 5%",
        "description": "IGST",
        "section": "IGST",
        "rate": 5,
        "rateType": "PERCENTAGE",
        "dateCreated": "2026-04-08T03:14:10.902Z",
        "entityGstin": "29AAJCM3528P1ZR",
        "entityGstinName": "MDP Coffee House"
      }
    ]
  }
}
```

### Empty Result

An organization with no GST taxes configured returns `200` with an empty array, not an error:

```json theme={null}
{
  "ok": true,
  "data": {
    "gstList": []
  }
}
```

## Error Responses

### Authentication Errors

**HTTP Status:** `401 Unauthorized`

```json theme={null}
{
  "ok": false,
  "error": {
    "code": "MISSING_CREDENTIALS",
    "message": "Missing Credentials"
  }
}
```

```json theme={null}
{
  "ok": false,
  "error": {
    "code": "INVALID_API_KEY",
    "message": "Invalid API Key"
  }
}
```

### Permission Errors

**HTTP Status:** `403 Forbidden`

Returned when the API key doesn't have the **Tax** resource with the **Read** action enabled.

```json theme={null}
{
  "ok": false,
  "error": {
    "code": "INSUFFICIENT_PERMISSIONS",
    "message": "Permission check failed - PERMISSION_CHECK_FAILED"
  }
}
```

### Rate Limiting

**HTTP Status:** `429 Too Many Requests`

```json theme={null}
{
  "ok": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded"
  }
}
```

### Server Errors

**HTTP Status:** `500 Internal Server Error`

```json theme={null}
{
  "ok": false,
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "An unexpected error occurred"
  }
}
```

## Best Practices

* Use `id` as the `gstId` when creating a vendor advance, and compute the expected `gstAmount` from `rate` and `rateType` — the create API validates your figure against its own calculation and rejects a mismatch
* Filter by `entityGstin` when your organization has multiple GSTIN entities, and keep it consistent with the `orgEntity` you send on the transaction
* Refresh this list at the start of each integration run rather than hardcoding ids; taxes are added and retired over time
* Match on `section` and `rate` (not `label`) when mapping to your own tax master — labels are free text set by the organization