Get, update, or archive a tax rate
API Documentation / Resources / Accounts and settings
Get a tax rate
GET /v1/tenants/{tenant_id}/subsidiaries/{subsidiary_id}/tax-rates/{tax_rate_id}
Required OAuth scope: accounting:read
Returns one tax rate by UUID within the granted subsidiary context.
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. |
tax_rate_id |
path | Yes | string (uuid) | UUID of a tax rate configured for the subsidiary. |
Request
GET /v1/tenants/{tenant_id}/subsidiaries/{subsidiary_id}/tax-rates/{tax_rate_id} HTTP/1.1
Host: api.finov.io
Authorization: Bearer {access_token}
Responses
| Status | Description |
|---|---|
200 |
Tax-rate details. |
401 |
Access token is missing, expired, revoked, or invalid. |
403 |
Token lacks the required scope or granted accounting context. |
404 |
Resource does not exist in the granted accounting context. |
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"
}
}
Update a tax rate
PATCH /v1/tenants/{tenant_id}/subsidiaries/{subsidiary_id}/tax-rates/{tax_rate_id}
Required OAuth scope: accounting:write
Updates tax calculation or presentation fields while preserving the immutable public code.
Posted transactions retain their stored tax amounts after this update; the new configuration applies only to subsequent calculations.
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. |
tax_rate_id |
path | Yes | string (uuid) | UUID of a tax rate configured for the subsidiary. |
Request
PATCH /v1/tenants/{tenant_id}/subsidiaries/{subsidiary_id}/tax-rates/{tax_rate_id} HTTP/1.1
Host: api.finov.io
Authorization: Bearer {access_token}
Content-Type: application/json
{
"name": "GST standard rate",
"percentage": "15.0000"
}
Required body fields: None.
Responses
| Status | Description |
|---|---|
200 |
Updated tax rate. |
401 |
Access token is missing, expired, revoked, or invalid. |
403 |
Token lacks the required scope or granted accounting context. |
404 |
Resource does not exist in the granted accounting context. |
409 |
Request conflicts with uniqueness or accounting state. |
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"
}
}
Archive a tax rate
DELETE /v1/tenants/{tenant_id}/subsidiaries/{subsidiary_id}/tax-rates/{tax_rate_id}
Required OAuth scope: accounting:write
Archives a rate for future use. Existing posted transactions retain their original tax code, percentage, and calculated amount.
A rate required by active configuration or protected accounting behavior
returns 409 tax_rate_in_use instead of being archived.
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. |
tax_rate_id |
path | Yes | string (uuid) | UUID of a tax rate configured for the subsidiary. |
Request
DELETE /v1/tenants/{tenant_id}/subsidiaries/{subsidiary_id}/tax-rates/{tax_rate_id} HTTP/1.1
Host: api.finov.io
Authorization: Bearer {access_token}
Responses
| Status | Description |
|---|---|
204 |
Tax rate archived. The response has no body. |
401 |
Access token is missing, expired, revoked, or invalid. |
403 |
Token lacks the required scope or granted accounting context. |
404 |
Resource does not exist in the granted accounting context. |
409 |
Request conflicts with uniqueness or accounting state. |