# Manage tax rates

Tax rates allow you to define VAT or other local tax percentages.
These tax rates can be assigned to financial records such as [expenses](/docs/guides/manage-accounts/accounts-and-transactions/retrieve-expenses) or [bills](https://help.revolut.com/business/help/integrating-with-external-apps/introduction-to-billpay/) to simplify your bookkeeping processes.

To manage tax rates via API, you must use an access token with the following [scopes](/docs/guides/manage-accounts/get-started/make-your-first-api-request#3-consent-to-the-application):

| Operation                                                                                             | Required Scope |
| :---------------------------------------------------------------------------------------------------- | :------------- |
| [Retrieve tax rates](#retrieve-tax-rates)                                                             | `READ`         |
| [Create](#create-a-tax-rate), [update](#update-a-tax-rate), or [delete](#delete-a-tax-rate) tax rates | `WRITE`        |

:::note
The `WRITE` operations are not supported for [externally managed tax rates](#externally-managed-settings).
:::

## Create a tax rate

:::note
This operation is not supported for [externally managed tax rates](#externally-managed-settings).
:::

To add a new tax rate, you must provide the following details:

- **Name:** A unique name for the tax rate that helps to understand its application.
- **Percentage:** The percentage for the tax rate, provided as number (from `0` to `100`). For example, `23` or `23.00` for 23 %.

:::note
On success, the response returns only the ID of the created tax rate.
To get all the details, use that ID to [retrieve a specific tax rate](#retrieve-a-specific-tax-rate).
:::

For more details and sample requests and responses:

[See the API reference: Create a tax rate](/docs/api/business#create-tax-rate)

## Retrieve tax rates

You can use the API to retrieve tax rates available for your business.

When you retrieve the tax rates, for each tax rate, you get its details, such as the tax rate ID, name, and percentage, as well as when it was created and when it was last updated.

You can:

- [Retrieve all the tax rates](#retrieve-a-list-of-tax-rates) available in your settings
- [Retrieve a specific tax rate](#retrieve-a-specific-tax-rate)

:::note
You cannot create negative tax rates manually.
However, negative tax rates might be synced from your accounting software, if integrated.
:::

### Retrieve a list of tax rates

When you list all the tax rates available for your business, the results are [paginated](#pagination) and sorted by the `created_at` date in reverse chronological order.
To get the next page of results, use the `next_page_token` value.

For more details and sample requests and responses:

[See the API reference: Retrieve a list of tax rates](/docs/api/business#get-tax-rates)

### Retrieve a specific tax rate

You can also retrieve a specific tax rate by its ID to look up its name, percentage, and dates of creation and last update.

For more details and sample requests and responses:

[See the API reference: Retrieve a tax rate](/docs/api/business#get-tax-rate)

## Update a tax rate

:::note
This operation is not supported for [externally managed tax rates](#externally-managed-settings).
:::

You can use the PATCH request to update the name for a specific tax rate.
This can be useful, for example, when there's a typing error in the name, or when the name of the tax itself has changed.

:::note
Percentage updates are not supported.
If you need to set a new percentage for a tax, you can:

- [Create](#create-a-tax-rate) a new tax rate with a new name and switch to using this new rate
- [Delete](#delete-a-tax-rate) the existing tax rate and [create](#create-a-tax-rate) a new one under the same name with the correct percentage.
  - Optionally, instead of deleting, you can rename the existing tax rate, and create a new one with the name that has been freed up.
:::

On successful update, you get a `204` response with no additional content.

For more details and sample requests and responses:

[See the API reference: Update a tax rate](/docs/api/business#update-tax-rate)

## Delete a tax rate

:::note
This operation is not supported for [externally managed tax rates](#externally-managed-settings).
:::

To delete a tax rate, simply make a DELETE call providing the ID of this tax rate.

:::warning [Deletion consequences for financial records]
Once a tax rate is deleted, it is removed from the Revolut Business app.
Existing records with the deleted tax rate that are pending completion will be marked as **invalid**, and they will require a manual update to a valid tax rate.
Complete records are not affected.

See an example of an incomplete expense with accounting settings that have been deleted, now marked as invalid →

![img](/img/manage-accounts/accounting-invalid-expense.png)
:::

On successful deletion, you get a `204` response with no additional content.

For more details and sample requests and responses:

[See the API reference: Delete a tax rate](/docs/api/business#delete-tax-rate)

## Pagination

- **Page size**: The API returns a maximum of 500 results per request (default: 100).
  You can increase or decrease the page size, i.e. the maximum number of results returned per page, by explicitly setting the `limit` parameter.
- **Sorting**: Results are sorted by the `created_at` date in reverse chronological order.
- **Next Page**: If the results exceed the page size, the response includes `next_page_token`.
  To fetch the next page of results, make a new request providing this value of `next_page_token` in the `page_token` query parameter.

## Externally managed settings

If an accounting software [integration](https://www.revolut.com/business/integrations/) is connected, tax rates are typically managed within that external platform.
In this state, the tax rates are **read-only** via the API, and manual modification attempts will return an error.

:::tip
To find out if your tax rates are managed externally, check the [Revolut Business settings](https://business.revolut.com/settings).

1. Go to **Settings** → **Accounting** → [**Tax rates**](https://business.revolut.com/settings/accounting/tax-rates).
2. Look for a **+ New** button above the tax rates.

- If you see the button, this means that your tax rates can be modified via the API.
- If you don't see the button, your tax rates are managed externally by the connected integration and cannot be modified (created/updated/deleted) via the API.
  The name of the connected integration appears near the top, together with information when it was last synced.

| Editable                                                       | Read-only                                                     |
| -------------------------------------------------------------- | ------------------------------------------------------------- |
| ![img](/img/manage-accounts/accounting-tax-rates-editable.png) | ![img](/img/manage-accounts/accounting-tax-rates-managed.png) |
:::

## See also

- [Accounting settings - overview](/docs/guides/manage-accounts/accounting/manage-accounting-settings)
- [Manage accounting categories](/docs/guides/manage-accounts/accounting/manage-accounting-categories)
- [Manage labels and label groups](/docs/guides/manage-accounts/accounting/manage-labels-and-label-groups)
- Revolut Help Centre:
  - [Expenses](/docs/guides/manage-accounts/accounts-and-transactions/retrieve-expenses)
  - [Bills](https://help.revolut.com/business/help/integrating-with-external-apps/introduction-to-billpay/)