> ## 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 Export API (v3)

> Migration guide from the legacy Tax Code API to the Export API (v3). Use it if you book expenses in an Accounting System. Each Export Item line carries its Tax Code, so you no longer look it up. To manage Tax Codes, see Migrate to the New Tax Code API.

This guide is for partners who used the [legacy Tax Code API](https://developers.pleo.io/reference/pleo-deprecated/tax-codes/get-a-tax-code-for-a-company.md) to look up the Tax Code of each expense that they book in an Accounting System. If you read the Tax Codes of a company, for example to keep them in step with an Accounting System, see [Migrate to the New Tax Code API](https://developers.pleo.io/deprecation/legacy-tax-code-api/migrate-to-tax-code-api.md) instead.

> **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 read the Tax Code of an expense during an export?

Fetch the Export Items with `GET /v3/export-items?job_id={jobId}` and read `accountingEntryLines[].tax`. You no longer call a Tax Code endpoint for each expense.

* The `tax` object can be `null`, because not every line has a Tax Code.
* Match on `tax.code`, which is the identifier in the Accounting System.
* If nothing matches, fail the Export Item with the `tax_code_unknown` failure reason.

> **Sources for the Export API:**
>
> * OpenAPI reference: the endpoint pages under the [Export API Overview](https://developers.pleo.io/reference/export-api/export-api-overview.md). Use the v3 pages for new work. The [Export API Workflow](https://developers.pleo.io/reference/export-api/export-api-workflow.md) explains the order of the calls.
> * Attachments: [Attachments](https://developers.pleo.io/docs/current/platform/exports/attachments.md) explains the receipt file limits.
> * How-tos, all under `/docs/current/how-tos/accounting-integrations/`: [How to Detect and Start Export Jobs for Processing](https://developers.pleo.io/docs/current/how-tos/accounting-integrations/how-to-detect-and-start-export-jobs-for-as-erp-processing.md), [How to Retrieve Export Job Items for Processing](https://developers.pleo.io/docs/current/how-tos/accounting-integrations/how-to-retrieve-export-job-items-for-as-erp-processing.md), [How to Fetch Export Item Data for Processing](https://developers.pleo.io/docs/current/how-tos/accounting-integrations/how-to-fetch-export-item-data-for-as-erp-processing.md), [How to Transfer Attachments](https://developers.pleo.io/docs/current/how-tos/accounting-integrations/how-to-transfer-attachments-for-as-erp-processing.md), [How to Update Export Items](https://developers.pleo.io/docs/current/how-tos/accounting-integrations/how-to-update-export-items-for-as-erp-processing.md) and [How to Update & Complete the Export Job](https://developers.pleo.io/docs/current/how-tos/accounting-integrations/how-to-update-and-complete-export-job-for-as-erp-processing.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 reading tax data on Export Items, using the Export API v3. Related pages cover different concerns:
>
> * [Migrate to the New Tax Code API](https://developers.pleo.io/deprecation/legacy-tax-code-api/migrate-to-tax-code-api.md): managing tax codes (create, update, search), not reading them on exports.
> * [Legacy Tax Code API Overview](https://developers.pleo.io/deprecation/legacy-tax-code-api/overview.md): helps you choose between the two.

## New to the Export API (v3)?

> [card] [Export Workflow Guide](https://developers.pleo.io/docs/current/guides/export-integration-workflow-guide.md)
>
> End-to-end walkthrough of the Export API (v3) integration model.

> [card] [Data Mapping](https://developers.pleo.io/docs/current/integration-design/exports/integration-design-exports-data-mapping.md)
>
> How to map Export Item fields, including the Tax Code and VAT, to your Accounting System.

> [card] [API Scopes](https://developers.pleo.io/reference/export-api/export-api-scopes.md)
>
> Required scopes: `export-jobs:write`, `export-jobs:read`, `export-items:read`.

> [card] [OAuth 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.

> [card] [Migrate from the Expenses API](https://developers.pleo.io/deprecation/legacy-expense-api/migration-guide-expenses-api-to-export-api.md)
>
> The full export steps for integrations that used the Expenses API.

## What Changes in Your Integration

With the legacy APIs, an expense only held a `taxCodeId`. You called the legacy Tax Code API to turn that identifier into a Tax Code. With the Export API (v3), Pleo includes the tax details on each Accounting Entry line of the Export Item. You fetch the Export Items of an Export Job, so the Tax Codes arrive in that response. You no longer call a Tax Code endpoint for each expense.

| Step | Before (legacy Tax Code API) | After (Export API (v3)) |
| :- | :- | :- |
| Start the work | Not applicable | `POST /v3/export-job-events` with `"event": "started"` |
| Find the Tax Code of an expense | `GET /tax-codes` or `GET /tax-codes/{taxCodeId}`, matched to `taxCodeId` on the expense | `GET /v3/export-items?job_id={jobId}`. Read `accountingEntryLines[].tax` |
| Read the Tax Code | `code`, `rate`, `type`, `ingoingTaxAccount` and `outgoingTaxAccount` | The same data on `tax`. The `tax` object also has the tax `amount` |

### Reading Tax Codes from Export Items

1. Detect a `pending` Export Job and start it with `POST /v3/export-job-events` and `"event": "started"`. The Export Job is now `in_progress`.
2. Fetch the Export Items with `GET /v3/export-items?job_id={jobId}`. This endpoint is paginated. The `limit` parameter sets the page size only. To read every page, pass `pagination.endCursor` as `after` in the next request until `pagination.hasNextPage` is `false`.
3. Read the `tax` object on each Accounting Entry line, in `accountingEntryLines[]`.
4. Match `tax.code` to the Tax Code in the Accounting System, and use it when you create the entry.

You need the `export-jobs:write` scope to start the Export Job and the `export-items:read` scope to fetch the Export Items.

The `tax` object can be `null`, because not every Accounting Entry line has a Tax Code. Pleo usually provides the `code`, the `id`, or both. Match on `code`, because it is the identifier of the Tax Code in the Accounting System. The `id` is the Pleo identifier of the Tax Code.

If the Accounting System has no Tax Code that matches `tax.code`, mark the Export Item as failed with the `tax_code_unknown` failure reason. For more information, see [Update and Complete an Export Job](https://developers.pleo.io/docs/current/integration-design/exports/integration-design-exports-update-and-complete-export-job.md).

Note

The Export API (v3) returns the Tax Code of each Accounting Entry line. It does not return the list of all Tax Codes of a company. To read that list, use the [new Tax Code API](https://developers.pleo.io/deprecation/legacy-tax-code-api/migrate-to-tax-code-api.md).\
\
You can only fetch Export Items while the Export Job is `pending` or `in_progress`.

### VAT Amounts

The Export API (v3) also returns the tax `amount` of each Accounting Entry line, in the supplier currency and in the wallet currency. The legacy Tax Code API had no amounts. Only send the VAT amount to your Accounting System if it cannot calculate VAT itself. For more information, see [Data Mapping](https://developers.pleo.io/docs/current/integration-design/exports/integration-design-exports-data-mapping.md).

[Get Export Items →](https://developers.pleo.io/reference/export-api/export-items-v3/get-export-items.md)

## Field Mapping

The table below maps the fields of the legacy Tax Code API response to the fields of the `tax` object on an Accounting Entry line of an Export Item, in `accountingEntryLines[]`.

* `—` : field is not available in the Export API (v3)
* `*` : data is the same but represented differently

| Legacy field | `tax` equivalent | Description |
| :- | :- | :- |
| id | `id` | The unique identifier that Pleo generates for the Tax Code. |
| name | — | The name of the Tax Code. The Export API (v3) does not return it. |
| code | `code` | The Accounting System identifier of the Tax Code. It can be `null`. |
| rate | `rate` | The tax rate as a decimal, for example `0.20` for 20%. |
| type | `type` **\*** | `NORMAL` becomes `inclusive`. `REVERSE` becomes `reverse`. The API specification also lists `exclusive`, but Pleo does not currently support it, so you do not receive it. |
| ingoingTaxAccount | `ingoingTaxAccount` | The ingoing tax account. It is used alongside Tax Codes or for reverse charge VAT. |
| outgoingTaxAccount | `outgoingTaxAccount` | The outgoing tax account. It is used alongside Tax Codes or for reverse charge VAT. |
| enabled | — | The Export API (v3) returns only the Tax Code that the Accounting Entry line uses, so there is no enabled or archived state. |
| createdAt | — | The Export API (v3) does not return it. |
| updatedAt | — | The Export API (v3) does not return it. |
| deletedAt | — | The Export API (v3) does not return it. |
| — | `amount` | The tax amount of the Accounting Entry line, in `inSupplierCurrency` and `inWalletCurrency`. |

[Data Mapping Integration Design →](https://developers.pleo.io/docs/current/integration-design/exports/integration-design-exports-data-mapping.md)
