> ## 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 Tax Creation API

> Create a GST tax rate for your organization

## Authentication

All requests require an API key in the request headers.

**Headers:**

```
Authorization: Api-Key YOUR_API_KEY
Content-Type: application/json
```

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

## Request

**Content-Type:** `application/json`

Creates a custom GST rate in your organization tax master. Use the returned `id` as `gstId` when creating vendor advances or other transactions that need GST.

GST rates are scoped to an organization entity when you pass `entityGstin`. Resolve available GSTINs from the [Company Entities API](/apis/company-entities). To list rates that already exist, use the [GST Taxes API](/apis/taxes-gst).

<Info>
  This endpoint creates standard (non reverse-charge) percentage rates — the same shape returned by the list API.
</Info>

### Body Parameters

| Parameter     | Type   | Required | Constraints             | Description                                                                                 |
| ------------- | ------ | -------- | ----------------------- | ------------------------------------------------------------------------------------------- |
| `name`        | string | Yes      | 1–255 characters        | Display name for the rate in Pazy (returned as `label` on list)                             |
| `section`     | string | Yes      | `IGST` or `SGST + CGST` | GST component — interstate vs intrastate split                                              |
| `rate`        | number | Yes      | 0–100                   | Tax percentage                                                                              |
| `entityGstin` | string | No       | 15-character GSTIN      | Organization entity GSTIN this rate belongs to. Omit to leave the rate unbound to an entity |

## Code Examples

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.pazy.io/v1.0/taxes/gst \
    -H "Authorization: Api-Key YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "GST 18%",
      "section": "IGST",
      "rate": 18,
      "entityGstin": "29AAJCM3528P1ZR"
    }'
  ```

  ```javascript JavaScript (Fetch API) theme={null}
  const response = await fetch('https://api.pazy.io/v1.0/taxes/gst', {
    method: 'POST',
    headers: {
      Authorization: 'Api-Key YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'GST 18%',
      section: 'IGST',
      rate: 18,
      entityGstin: '29AAJCM3528P1ZR'
    })
  });

  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",
      "Content-Type": "application/json"
  }
  payload = {
      "name": "GST 18%",
      "section": "IGST",
      "rate": 18,
      "entityGstin": "29AAJCM3528P1ZR"
  }

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

## Success Response

**HTTP Status:** `200 OK`

**Response Fields:**

| Field                      | Type           | Description                                                         |
| -------------------------- | -------------- | ------------------------------------------------------------------- |
| `ok`                       | boolean        | Indicates whether the request was successful                        |
| `data.tax.id`              | string         | Tax id. Pass this as `gstId` to transaction create APIs             |
| `data.tax.label`           | string         | Display name given to the tax                                       |
| `data.tax.description`     | string         | Same value as `section`                                             |
| `data.tax.section`         | string         | GST component e.g. `IGST`, `SGST + CGST`                            |
| `data.tax.rate`            | number         | Tax percentage                                                      |
| `data.tax.rateType`        | string         | How `rate` is applied — `PERCENTAGE` for rates created via this API |
| `data.tax.dateCreated`     | string         | ISO 8601 timestamp of when the tax was created                      |
| `data.tax.entityGstin`     | string \| null | GSTIN passed in the request, or `null` when omitted                 |
| `data.tax.entityGstinName` | string \| null | Entity display name when available; may be `null` on create         |

### Response Example

```json theme={null}
{
  "ok": true,
  "data": {
    "tax": {
      "id": "4172",
      "label": "GST 18%",
      "description": "IGST",
      "section": "IGST",
      "rate": 18,
      "rateType": "PERCENTAGE",
      "dateCreated": "2026-09-02T06:45:12.110Z",
      "entityGstin": "29AAJCM3528P1ZR",
      "entityGstinName": null
    }
  }
}
```

## Error Responses

### Validation Errors

**HTTP Status:** `400 Bad Request`

Returned when `section` is invalid or `entityGstin` does not match an active organization GSTIN.

```json theme={null}
{
  "ok": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Organization entity GSTIN not found: 29AAJCM3528P1ZR"
  }
}
```

### 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 **Create** 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

* Pass `entityGstin` when your organization has multiple GSTIN entities so the rate shows up for the right entity on list and transaction flows
* Use `section` values exactly as documented (`IGST` or `SGST + CGST`) — free-text labels are rejected
* After create, confirm the rate on [List GST Taxes](/apis/taxes-gst) before hardcoding the id in downstream jobs