List or create tax rates
API Documentation / Resources / Accounts and settings
List tax rates
GET /v1/tenants/{tenant_id}/subsidiaries/{subsidiary_id}/tax-rates
Required OAuth scope: accounting:read
Lists tax rates configured for the subsidiary.
Filter by active or exact code, and use search for code or name.
Sort by code, name, percentage, or updated_at; the default is
code ASC followed by stable resource order.
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
tenant_id |
path | Yes | string (uuid) | UUID of the authorized company group. |
subsidiary_id |
path | Yes | string (uuid) | UUID of the subsidiary whose books contain the bank account. |
active |
query | No | boolean | |
code |
query | No | string | |
search |
query | No | string | |
page |
query | No | integer | |
per_page |
query | No | integer | |
sort |
query | No | string: code, name, percentage, updated_at | |
order |
query | No | string: asc, desc |
Request
GET /v1/tenants/{tenant_id}/subsidiaries/{subsidiary_id}/tax-rates HTTP/1.1
Host: api.finov.io
Authorization: Bearer {access_token}
Responses
| Status | Description |
|---|---|
200 |
A page of tax rates. |
401 |
Access token is missing, expired, revoked, or invalid. |
403 |
Token lacks the required scope or granted accounting context. |
422 |
One or more supplied values failed validation. |
200 example
HTTP/1.1 200 OK
Content-Type: application/json
{
"data": [
{
"id": "d98226c2-ad80-4345-b117-5630de766842",
"code": "GST15",
"name": "GST 15%",
"percentage": "15.0000",
"treatment": "OUTPUT",
"tax_account_id": "a110c7ae-3208-4f93-a64c-d2ba9dd82c32",
"active": true,
"created_at": "2026-08-10T11:30:00Z",
"updated_at": "2026-08-10T11:30:00Z"
}
],
"meta": {
"current_page": 1,
"per_page": 30,
"last_page": 1,
"total": 1
}
}
Create a tax rate
POST /v1/tenants/{tenant_id}/subsidiaries/{subsidiary_id}/tax-rates
Required OAuth scope: accounting:write
Creates a tax rate and links it to the liability account used for tax settlement.
| Field | Contract |
|---|---|
percentage |
Decimal string where 15.0000 means 15 percent. |
treatment |
Determines input, output, exempt, zero-rated, or out-of-scope behavior. |
tax_account_id |
Must identify an eligible provision account. |
Codes are unique within the subsidiary and remain immutable after create.
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
tenant_id |
path | Yes | string (uuid) | UUID of the authorized company group. |
subsidiary_id |
path | Yes | string (uuid) | UUID of the subsidiary whose books contain the bank account. |
Request
POST /v1/tenants/{tenant_id}/subsidiaries/{subsidiary_id}/tax-rates HTTP/1.1
Host: api.finov.io
Authorization: Bearer {access_token}
Content-Type: application/json
{
"code": "GST15",
"name": "GST 15%",
"percentage": "15.0000",
"treatment": "OUTPUT",
"tax_account_id": "a110c7ae-3208-4f93-a64c-d2ba9dd82c32"
}
Required body fields: code, name, percentage, treatment, tax_account_id.
Responses
| Status | Description |
|---|---|
201 |
Tax rate created. |
401 |
Access token is missing, expired, revoked, or invalid. |
403 |
Token lacks the required scope or granted accounting context. |
409 |
Request conflicts with uniqueness or accounting state. |
422 |
One or more supplied values failed validation. |
201 example
HTTP/1.1 201 Created
Content-Type: application/json
{
"data": {
"id": "d98226c2-ad80-4345-b117-5630de766842",
"code": "GST15",
"name": "GST 15%",
"percentage": "15.0000",
"treatment": "OUTPUT",
"tax_account_id": "a110c7ae-3208-4f93-a64c-d2ba9dd82c32",
"active": true,
"created_at": "2026-08-10T11:30:00Z",
"updated_at": "2026-08-10T11:30:00Z"
}
}