finov.ioDocumentationHome

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"
  }
}