finov.ioDocumentationHome

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.