> ## Documentation Index
> Fetch the complete documentation index at: https://developers.pleo.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Migrate to the New Tax Code API

> Migration guide from the legacy Tax Code API (/tax-codes) to the new Tax Code API (/v0/tax-codes). Use it if you read Tax Codes. The new API also creates, updates and deletes them. For Tax Codes on exported expenses, see Migrate to the New Export API (v3).

This guide is for partners who used the legacy Tax Code API to read the Tax Codes of a company. If you used it to look up the Tax Codes of expenses that you book in an Accounting System, see [Migrate to the New Export API (v3)](https://developers.pleo.io/deprecation/legacy-tax-code-api/migrate-to-export-api.md) instead.

The legacy Tax Code API has been deprecated. This guide covers how to migrate to the [new Tax Code API](https://developers.pleo.io/reference/tax-codes-overview.md).

> **Use this page to answer:**

### Which API replaces the legacy Tax Code API?

It depends on the use case.

* To read and manage the Tax Codes of a company, use the new Tax Code API.
* To get the Tax Code of an exported expense, use the Export API (v3). It returns the Tax Code on each Accounting Entry line in `accountingEntryLines[].tax`.

To choose, see the [Legacy Tax Code API Overview](https://developers.pleo.io/deprecation/legacy-tax-code-api/overview.md).

### How do I map the legacy Tax Code fields to the new Tax Code API?

* Map the legacy type `NORMAL` to `inclusive` and `REVERSE` to `reverse`. Do not map either to `exclusive`, which is in the specification but is not currently supported.
* The legacy `enabled` field is now `archived`, and the value is the opposite.
* The new `rate` is a decimal, for example `0.20` for 20%.
* The new search is `POST /v0/tax-codes:search`. It returns archived and active Tax Codes unless you send `"archived": false`.

> **Sources for the Tax Code API:**
>
> * OpenAPI reference: the endpoint pages under the [Tax Code API Overview](https://developers.pleo.io/reference/tax-codes-overview.md). Use them for paths, parameters and required fields.
> * How-tos: [How to Fetch and Match Tax Codes](https://developers.pleo.io/docs/current/how-tos/accounting-integrations/imports/tax-codes/how-to-fetch-and-match-tax-codes.md) and [How to Create, Update, and Archive Tax Codes](https://developers.pleo.io/docs/current/how-tos/accounting-integrations/imports/tax-codes/how-to-create-update-archive-tax-codes.md).
> * If a how-to and the reference disagree, trust the how-to. How-tos record tested behaviour.

> This page is the canonical source for managing tax codes with the new Tax Code API. Related pages cover different concerns:
>
> * [Migrate to the Export API (v3)](https://developers.pleo.io/deprecation/legacy-tax-code-api/migrate-to-export-api.md): reading tax data on Export Items.
> * [Legacy Tax Code API Overview](https://developers.pleo.io/deprecation/legacy-tax-code-api/overview.md): helps you choose between the two.

Terminology: Legacy and New

Both APIs are called the Tax Code API. This guide calls the deprecated API the **legacy Tax Code API** and its replacement the **new Tax Code API**.

The legacy Tax Code API has two read endpoints under `https://openapi.pleo.io/v1/`. The new Tax Code API is under `https://external.pleo.io`, and its endpoints start with `/v0/`.

## New to the New Tax Code API?

> [card] [API Overview](https://developers.pleo.io/reference/tax-codes-overview.md)
>
> What a Tax Code is and how the new API is structured.

> [card] [API Scopes](https://developers.pleo.io/reference/scopes-3.md)
>
> Required scopes: `tax-codes:read` and `tax-codes:write`.

> [card] [Tax Sync Overview](https://developers.pleo.io/docs/current/platform/accounting-integrations/imports/tax-codes/tax-sync-overview.md)
>
> How Tax Codes are kept in step with an Accounting System, and how Tax Codes are used in Pleo.

> [card] [OAuth 2.0 Guide](https://developers.pleo.io/docs/current/guides/oauth-workflow-guide.md)
>
> End-to-end OAuth 2.0 workflow guide for Pleo integrations.

> [card] [Standalone API Key Guide](https://developers.pleo.io/docs/current/guides/standalone-api-keys-workflow-guide.md)
>
> End-to-end guide for authenticating with standalone API keys.

## Getting Started

You need API credentials with the [`tax-codes:read`](https://developers.pleo.io/reference/scopes-3) scope to read Tax Codes. You also need the `tax-codes:write` scope if you create or update Tax Codes.

The new Tax Code API takes the company in different places by endpoint. `POST /v0/tax-codes:search` takes the `company_id` query parameter. Create and update requests take `companyId` in the JSON body. If you manage more than one company, handle each company on its own. For more information, see [Multi-Entity and API Scope](https://developers.pleo.io/docs/current/platform/multi-entity/multi-entity-and-api-scope.md).

## Endpoint Mapping

The table below maps the endpoints of the legacy Tax Code API to the endpoints of the new Tax Code API.

* `—` : endpoint is not available in the legacy Tax Code API

| Legacy Tax Code API | New Tax Code API | Description |
| :- | :- | :- |
| [`GET /tax-codes`](https://developers.pleo.io/reference/pleo-deprecated/tax-codes/get-tax-codes-for-a-company) | [`POST /v0/tax-codes:search`](https://developers.pleo.io/reference/tax-codes/returns-a-list-of-tax-codes) | Returns the Tax Codes of a company. The new endpoint is a search. You send the filters in the request body. |
| [`GET /tax-codes/{taxCodeId}`](https://developers.pleo.io/reference/pleo-deprecated/tax-codes/get-a-tax-code-for-a-company) | [`GET /v0/tax-codes/{taxCodeId}`](https://developers.pleo.io/reference/tax-codes/returns-a-given-tax-code) | Returns one Tax Code. |
| — | [`POST /v0/tax-codes`](https://developers.pleo.io/reference/tax-codes/create-a-new-tax-code) | Creates a Tax Code. |
| — | [`PUT /v0/tax-codes/{taxCodeId}`](https://developers.pleo.io/reference/tax-codes/update-an-tax-code) | Updates a Tax Code. Use it to archive or unarchive a Tax Code. |
| — | [`DELETE /v0/tax-codes/{taxCodeId}`](https://developers.pleo.io/reference/tax-codes/delete-an-tax-code) | Deletes a Tax Code. |

## Key Differences

* The legacy Tax Code API could only read Tax Codes. The new Tax Code API can also create, update and delete them. To keep Tax Codes in step with an Accounting System, see the [Tax Sync Workflow Guide](https://developers.pleo.io/docs/current/guides/accounting-integrations/imports/tax-sync-workflow-guide.md). Tax Sync archives Tax Codes and does not delete them.
* The legacy `GET /tax-codes` endpoint returned a `taxCodes` list. The new search endpoint returns a `data` list and a `pagination` object. Use the `limit`, `after`, `before` and `offset` query parameters to page through the results. You can sort with `sorting_keys` and `sorting_order`.
* The legacy `hidden` query parameter included hidden Tax Codes. The new search endpoint returns both archived and active Tax Codes unless you set `archived` in the request body. To exclude archived Tax Codes, send `"archived": false`.
* The legacy `enabled` field is replaced by `archived`. The value is the opposite. A Tax Code that was `enabled: true` is now `archived: false`.
* The legacy `type` values were `NORMAL` and `REVERSE`. The new `type` values are `inclusive`, `exclusive` and `reverse`. Map `NORMAL` to `inclusive` and `REVERSE` to `reverse`. Do not map either legacy value to `exclusive`. The `exclusive` value is in the API specification, but it is not currently supported.
* The new search endpoint can also filter by `type` and `taxCodeIds`.
* The legacy `force` query parameter has no equivalent in the new Tax Code API.
* The legacy response did not include the company. Each new Tax Code has a `companyId`.
* The new Tax Code API returns `rate` as a decimal, for example `0.20` for a 20% tax rate.

Tax Codes on exported expenses

If you read legacy Expenses and used `taxCodeId` to look up a Tax Code, the Export API (v3) returns the tax details on each Accounting Entry line, in `accountingEntryLines[].tax`. For more information, see [Migrate to the New Export API (v3)](https://developers.pleo.io/deprecation/legacy-tax-code-api/migrate-to-export-api.md).

## Field Mapping

The table below maps the fields of the legacy Tax Code API response to the fields of the new Tax Code object.

* `—` : field is not available on the legacy model
* `*` : data is the same but represented differently

| Legacy field | New field | Description |
| :- | :- | :- |
| id | `id` | The unique identifier that Pleo generates for the Tax Code. |
| name | `name` | The name of the Tax Code. |
| code | `code` | The Accounting System identifier of the Tax Code. Use it to match Tax Codes between systems. |
| rate | `rate` | The tax rate as a decimal. |
| type | `type` **\*** | `NORMAL` becomes `inclusive`. `REVERSE` becomes `reverse`. Do not use `exclusive`. |
| ingoingTaxAccount | `ingoingTaxAccount` | The ingoing tax account. It is usually used for reverse VAT. |
| outgoingTaxAccount | `outgoingTaxAccount` | The outgoing tax account. It is usually used for reverse VAT. |
| enabled | `archived` **\*** | The value is the opposite. `enabled: true` is `archived: false`. |
| createdAt | `createdAt` | The date and time that Pleo created the Tax Code. |
| updatedAt | `updatedAt` | The date and time that the Tax Code was last updated. |
| deletedAt | — | The new Tax Code API does not return a deletion date. |
| — | `companyId` | The unique identifier of the company that the Tax Code belongs to. |
| — | `accountingIntegrationSystem` | The Accounting System that the Tax Code comes from. |

## Example

The legacy request returns the Tax Codes of the company:

```bash theme={null}
GET https://openapi.pleo.io/v1/tax-codes
```

The new request needs the `company_id` query parameter. To return only active Tax Codes, send `"archived": false` in the request body.

> [tab] OAuth 2.0
>
> ```bash theme={null}
> curl -X POST "https://external.pleo.io/v0/tax-codes:search?company_id=12abc3d4-e567-890e-1234-abc56e78fabc" \
>   -H "Authorization: Bearer <access_token>" \
>   -H "Content-Type: application/json" \
>   -d '{ "archived": false }'
> ```

> [tab] API Key
>
> ```bash theme={null}
> curl -X POST "https://external.pleo.io/v0/tax-codes:search?company_id=12abc3d4-e567-890e-1234-abc56e78fabc" \
>   -u "<api_key>:" \
>   -H "Content-Type: application/json" \
>   -d '{ "archived": false }'
> ```

The response contains the Tax Codes in `data` and the paging details in `pagination`.

[Returns a list of tax codes →](https://developers.pleo.io/reference/tax-codes/returns-a-list-of-tax-codes.md)
