Taxes API

Manage tax configurations for an organization — create, list, overview, update, and delete.

Authentication

All endpoints require a valid Bearer token in the Authorization header.

Endpoints

Method	Path	Description
GET	/api/tax/:orgId/list	List all taxes
GET	/api/tax/:orgId/overview	Get tax overview stats
POST	/api/tax/:orgId/create	Create a new tax
PUT	/api/tax/:orgId/:id/update	Update a tax
DELETE	/api/tax/:orgId/:id/delete	Delete a tax

Path Parameters

Parameter	Type	Description
orgId	string	Organization ID
id	string	Tax document ID

---

List Taxes

GET /api/tax/:orgId/list

Query Parameters

Parameter	Type	Default	Description
page	number	1	Page number
limit	number	10	Results per page
search	string	—	Search by tax name
type	string	—	Filter by type (GST, CGST, SGST, IGST, CESS, custom)

Success Response 200

{
  "success": true,
  "data": [
    {
      "_id": "64f1b2c3d4e5f6a7b8c9d0a4",
      "name": "CGST @ 9%",
      "rate": 9,
      "type": "CGST",
      "isActive": true,
      "createdAt": "2026-01-01T00:00:00.000Z"
    },
    {
      "_id": "64f1b2c3d4e5f6a7b8c9d0a5",
      "name": "SGST @ 9%",
      "rate": 9,
      "type": "SGST",
      "isActive": true,
      "createdAt": "2026-01-01T00:00:00.000Z"
    },
    {
      "_id": "64f1b2c3d4e5f6a7b8c9d0a6",
      "name": "IGST @ 18%",
      "rate": 18,
      "type": "IGST",
      "isActive": true,
      "createdAt": "2026-01-01T00:00:00.000Z"
    }
  ],
  "pagination": {
    "total": 8,
    "page": 1,
    "limit": 10,
    "totalPages": 1
  }
}

---

Tax Overview

GET /api/tax/:orgId/overview

Returns aggregate statistics across configured taxes.

Success Response 200

{
  "success": true,
  "data": {
    "totalTaxes": 8,
    "activeTaxes": 6,
    "inactiveTaxes": 2,
    "byType": [
      { "type": "CGST", "count": 2 },
      { "type": "SGST", "count": 2 },
      { "type": "IGST", "count": 2 },
      { "type": "CESS", "count": 1 },
      { "type": "custom", "count": 1 }
    ]
  }
}

---

Create Tax

POST /api/tax/:orgId/create

Request Body

{
  "name": "CGST @ 6%",
  "rate": 6,
  "type": "CGST"
}

Field	Type	Required	Description
name	string	Yes	Display name for the tax
rate	number	Yes	Tax rate as a percentage (e.g. 9 for 9 %)
type	string	Yes	Tax type — GST, CGST, SGST, IGST, CESS, or custom

Success Response 201

{
  "success": true,
  "message": "Tax created successfully",
  "data": {
    "_id": "64f1b2c3d4e5f6a7b8c9d0a7",
    "name": "CGST @ 6%",
    "rate": 6,
    "type": "CGST",
    "isActive": true,
    "orgId": "64f1b2c3d4e5f6a7b8c9d0e0",
    "createdAt": "2026-02-20T10:00:00.000Z",
    "updatedAt": "2026-02-20T10:00:00.000Z"
  }
}

Error Response 400

{
  "success": false,
  "message": "Validation error",
  "errors": [
    "name is required",
    "rate must be a positive number",
    "type must be one of: GST, CGST, SGST, IGST, CESS, custom"
  ]
}

Error Response 409

{
  "success": false,
  "message": "Tax 'CGST @ 6%' already exists"
}

---

Update Tax

PUT /api/tax/:orgId/:id/update

Request Body

{
  "name": "CGST @ 9%",
  "rate": 9,
  "isActive": true
}

Success Response 200

{
  "success": true,
  "message": "Tax updated successfully",
  "data": {
    "_id": "64f1b2c3d4e5f6a7b8c9d0a7",
    "name": "CGST @ 9%",
    "rate": 9,
    "type": "CGST",
    "isActive": true,
    "updatedAt": "2026-02-21T09:00:00.000Z"
  }
}

Error Response 404

{
  "success": false,
  "message": "Tax not found"
}

---

Delete Tax

DELETE /api/tax/:orgId/:id/delete

Success Response 200

{
  "success": true,
  "message": "Tax deleted successfully"
}

Error Response 404

{
  "success": false,
  "message": "Tax not found"
}

Error Response 409

{
  "success": false,
  "message": "Cannot delete tax currently in use by invoices or expenses"
}