> ## 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.

# FAQs

> FAQ page for the legacy Pleo API deprecation, grouped by legacy API. Use it to find which new API replaces a legacy one and the common migration pitfalls. For step-by-step guides, see the Migration Catalogue.

Browse frequently asked questions about migrating from the legacy Pleo APIs, grouped by legacy API.

> [card] [General](#general)
>
> Deadlines, communications and other questions that apply to every migration.

> [card] [Legacy Accounts API](#legacy-accounts-api)
>
> Moving accounts and categories to the Chart of Accounts API and the Bookkeeping Categories API.

> [card] [Legacy Company Balance API](#legacy-company-balance-api)
>
> Moving the company balance to the Company Balance API.

> [card] [Legacy Expense API](#legacy-expense-api)
>
> Moving expense exports to the Export API and expense data to the Accounting Entries API.

> [card] [Legacy Export API](#legacy-export-api)
>
> Choosing the right guide and moving from Export API v0, v1 or v2 to v3.

> [card] [Legacy Receipt API](#legacy-receipt-api)
>
> Getting receipts with the Export API or the Accounting Entries API.

> [card] [Legacy Tag Groups API](#legacy-tag-groups-api)
>
> Moving tag groups to the Tags API.

> [card] [Legacy Tax Code API](#legacy-tax-code-api)
>
> Moving tax codes to the Tax Code API and the Export API.

> [card] Coming soon: Legacy Teams API
>
> Moving teams to the Teams API and member details to the Employees API.

***

## General

### Timeline and deadline

#### When will the legacy APIs be switched off?

The legacy APIs reach end of life on 1 June 2027 at 14:00 CEST (12:00 UTC). Pleo switches them off at that time. Export API v0 and v1 are also deprecated. Migrate them directly to Export API (v3), without going through v2. See the guides for [v0 to v3](https://developers.pleo.io/deprecation/legacy-export-api/migrate-from-v0-to-v3.md) and [v1 to v3](https://developers.pleo.io/deprecation/legacy-export-api/migrate-from-v1-to-v3.md).

#### Do I need to move from Export API v2 to v3?

Pleo has not officially announced an end-of-life date for Export API v2, but the current estimated date aligns with 1 June 2027. Pleo recommends that you move to Export API v3 now, so that you are on the current version before v2 reaches end of life. To plan your move, see the Export API guide in the [migration catalogue](https://developers.pleo.io/deprecation/migration-guides.md).

#### What happens to my API requests after the end-of-life date?

Pleo blocks API requests to the legacy APIs. Migrate before 1 June 2027 at 14:00 CEST so your integration keeps working.

#### Will Pleo switch the legacy APIs off for short periods before the end-of-life date?

No. Pleo does not plan any short switch-offs before 1 June 2027 at 14:00 CEST. Your requests keep working until that time.

#### Will Pleo extend the deadline if I have not migrated?

No. The end-of-life date is 1 June 2027 at 14:00 CEST. If you need help to meet it, contact Pleo as early as you can.

#### When will the migration guides for every API be available?

Pleo publishes each guide as it is ready. The [migration catalogue](https://developers.pleo.io/deprecation/migration-guides.md) shows which guides are available now. Guides that are not ready show "Coming soon".

### Status of the legacy APIs

#### Will the legacy APIs still get fixes or new features?

No. Pleo does not add new features to the legacy APIs. Pleo may provide critical security updates and bug fixes where it is feasible to make them before the end-of-life date. Do not rely on a fix, and migrate to the new APIs instead.

#### Can I still create legacy API tokens?

Partly. Customers who already have access to legacy API tokens can still create them. Pleo does not give new customers access, unless they need to connect to a legacy integration.

#### Will my existing legacy API tokens keep working until the end-of-life date?

Yes. Existing legacy API tokens keep working until 1 June 2027 at 14:00 CEST.

### Who is affected

#### I do not have an accounting integration. Does the deprecation affect me?

It might. The deprecation affects you if anything you built calls a legacy API, whatever it does. This includes dashboards, reports, business intelligence (BI) tools and any other custom integration. Pleo is deprecating all the legacy APIs, so migrate anything that calls one to the new API before the end-of-life date. Use the [migration catalogue](https://developers.pleo.io/deprecation/migration-guides.md) to find the guide for each legacy API you use.

#### Are the pre-built integrations affected?

You should not be affected. Pleo and its partners handle the migration of the pre-built integrations (as listed on the [Pleo integrations page](https://www.pleo.io/en/integrations)), so you do not need to do anything. The deprecation affects custom integrations. These are integrations that you built yourself, or that a Pleo partner built for you.

#### Do I need to tell my employees about the migration?

Yes, where it affects them. For example, your developer teams need to migrate your integrations. Depending on how you built your integration, your finance team may see changes to the information in your connected accounting system, or in your dashboards and reports. Pleo does not inform your employees. You are responsible for telling them. Users will need to reconnect.

### Emails and notices

#### Who will Pleo email about the migration?

Pleo emails every company where it detects a custom integration with Pleo. The email goes to the developer, partner or any other applicable contact on record for that company. If you get the email but did not create an integration yourself, a Pleo partner may have created it for you. Ask your IT team who your integrator is. Then check with them that they have migrated your integration.

#### I have already migrated. Do I need to do anything?

No. Pleo emails everyone who currently has a legacy integration. After you migrate, you keep getting the emails until the end-of-life date. If you have migrated all your integrations, you can ignore the emails.

#### When will Pleo send the emails?

Pleo sends the first email when all the new APIs are available (estimated December 2026). You do not have to wait for the email to start migrating. Pleo then sends reminders about a quarter, half and three quarters of the way to the end-of-life date, and a final email on 1 June 2027, the end-of-life date.

#### How will I find out about the migration if Pleo does not know I use a legacy API?

Pleo cannot email legacy API callers it cannot identify. The announcement in the developer portal changelog and the banner in the Pleo Web App reach these legacy API callers instead.

#### Will Pleo contact me personally if I have not migrated?

Where Pleo can identify you, it may contact you directly and ask for a response. Pleo cannot identify every legacy API caller, so do not wait for personal contact. You are responsible for migrating before the end-of-life date.

#### Will Pleo tell me about the migration anywhere other than email?

Yes. Pleo also posts the announcement in the [developer portal changelog](https://developers.pleo.io/changelog.md).

#### Will I see a deprecation notice in the Pleo Web App?

Yes. Pleo shows a banner on the page in the Pleo Web App where you create API keys. The banner reminds users that Pleo is deprecating the legacy APIs and links to the [API Deprecation Notice](https://developers.pleo.io/deprecation/overview.md). For when the banner appears and when Pleo removes it, see [When will the notice appear, who will see it and when will it be removed?](https://developers.pleo.io/deprecation/faq.md#when-will-the-notice-appear-who-will-see-it-and-when-will-it-be-removed)

#### When will the notice appear, who will see it and when will it be removed?

The banner appears shortly after the announcement email. Users who open the page in the Pleo Web App where you create API keys see it. Pleo removes it after the end-of-life date.

#### Will I see a deprecation notice on the developer portal?

Yes. A banner appears on every page of the developer portal from the first email until the end-of-life date. You cannot dismiss it. Only the wording changes as the end-of-life date gets closer.

### Help

#### Who do I contact for help with the migration?

If you are a Pleo customer, contact your Pleo support contact. If you are a Pleo partner, email [api@pleo.io](mailto:api@pleo.io).

***

## Legacy Accounts API

Migration guides: [Overview](https://developers.pleo.io/deprecation/legacy-accounts-api/overview.md), [Chart of Accounts API](https://developers.pleo.io/deprecation/legacy-accounts-api/migrate-to-chart-of-accounts-api.md), [Bookkeeping Categories API](https://developers.pleo.io/deprecation/legacy-accounts-api/migrate-to-bookkeeping-categories-api.md).

### Which API replaces the legacy Accounts API?

Two APIs replace it.

* The Chart of Accounts API replaces `/accounts`, for example with `POST /v1/chart-of-accounts`.
* The Bookkeeping Categories API replaces `/account-groups`, for example with `POST /v1/bookkeeping-category-groups`.

If an integration does both, create the accounts first. A category links to an account through its `accountId`. To choose, see the [Legacy Accounts API Overview](https://developers.pleo.io/deprecation/legacy-accounts-api/overview.md).

### How does the Chart of Accounts API match accounts?

It matches accounts on `externalId`, not on `code` or `name`.

* `externalId` is the identifier of the account in the Accounting System. You must send it when you create an account.
* Pleo rejects a second account with the same `externalId`. In a batch create, the item appears in `data.failed[]` with `EXTERNAL_ID_ALREADY_EXISTS`, and the other valid items are still created.
* The legacy `accountNumber` is now `code`.

### Should I delete an account in production?

No. Archive it instead.

* Archive with a `PUT` request and `"archived": true`. The legacy `hidden` field is now `archived`.
* Pleo deletes an account at once, even when a category maps to it or accounting entries use it. Pleo does not return a `409`, and you cannot undo a delete.
* Use `DELETE` only to remove test accounts in staging.
* Chart of Accounts Sync archives accounts and does not delete them.

See [How to Delete an Account](https://developers.pleo.io/docs/current/how-tos/accounting-integrations/imports/accounts/how-to-delete-accounts.md).

### How do I change the account that a category uses?

Send a `PUT` request to `/v1/bookkeeping-categories/{categoryId}` with the new `accountId`.

* In the legacy API, an account belonged to one group through its `accountCategoryId`. The new category keeps the group in `categoryGroupId` and the account in `accountId`.
* The update request needs `archived`, `name` and `categoryGroupId`, so send the full category.

### Can I delete a category that is linked to accounts?

No. Pleo returns `409`. Archive the category instead with `"archived": true` if it must stay available for historical bookkeeping data. When you archive a category group, Pleo archives every category in the group.

***

## Legacy Company Balance API

Migration guide: [Company Balance API](https://developers.pleo.io/deprecation/legacy-company-api/overview.md).

### What replaces GET /companies/balance?

`GET /v1/companies/{companyId}/balance` in the Company Balance API replaces it.

* It needs the `company-balance:read` scope.
* The legacy endpoint used the company of the bearer token. The new endpoint takes an explicit `companyId` in the path.
* It returns `404` if the company is not found, `410` if the company accounts are closed, and `502` if the balance cannot be retrieved from an upstream dependency.

### How is the new balance response different?

* It returns a list of balances, one for each account, not one company-level balance. Most companies have a single primary account, so the list usually has one entry.
* Monetary values are `{ currency, value }` objects. The `value` is an integer in minor units of the currency, so check how your code reads the amount.
* The new endpoint also reports overdraft and pending-debit data for each account.

***

## Legacy Expense API

Migration guides: [Overview](https://developers.pleo.io/deprecation/legacy-expense-api/overview.md), [Export API (v3)](https://developers.pleo.io/deprecation/legacy-expense-api/migration-guide-expenses-api-to-export-api.md), [Accounting Entries API](https://developers.pleo.io/deprecation/legacy-expense-api/migrate-to-accounting-entries-api.md).

### Which API replaces the legacy Expenses API?

It depends on the use case.

* To export expenses to an Accounting System, use the Export API (v3).
* To fetch expense data for dashboards, reports or syncs, use the Accounting Entries API.

Pleo now calls expenses Accounting Entries, so the two terms mean the same thing. To choose, see the [Legacy Expense API Overview](https://developers.pleo.io/deprecation/legacy-expense-api/overview.md).

### How does the export workflow change from the Expenses API to the Export API (v3)?

The `v1.export-job.created` webhook replaces polling `GET /v1/expenses?status=QUEUED`. Then follow these steps:

1. Start the job with `POST /v3/export-job-events` and `"event": "started"`.
2. Fetch the data to export with `GET /v3/export-items?job_id={jobId}`.
3. Fetch the export tracking state with `GET /v3/export-jobs/{jobId}/items`.
4. Mark every item `in_progress` with `PUT /v3/export-jobs/{jobId}/items`. Do not skip this step. If you do, the expenses can stay in the **Queued** tab.
5. Export the data to your Accounting System. Then record the result of each item with `PUT /v3/export-jobs/{jobId}/items`. It has more detailed statuses than `PUT /v1/expenses`.
6. Complete the job with `POST /v3/export-job-events`. Send `"event": "completed"` if all items succeeded, `"completed_with_errors"` if some failed, or `"failed"` if all failed.

See [How to Resolve Export Items Stuck in the Export Queue](https://developers.pleo.io/docs/current/how-tos/accounting-integrations/how-to-resolve-export-items-stuck-in-queue.md) for the full sequence.

### How do I read expense data with the Accounting Entries API?

* Use the search endpoint to list Accounting Entries, and the get by ID endpoint to read one.
* You need at least the `accounting-entries:read` scope.
* The API uses cursor-based pagination.
* Field names and structure differ from the legacy Expenses API, so check the field mapping in the guide.

***

## Legacy Export API

Migration guides: [Overview](https://developers.pleo.io/deprecation/legacy-export-api/overview.md), [v2 to v3](https://developers.pleo.io/deprecation/legacy-export-api/migrate-from-v2-to-v3.md), [v1 to v3](https://developers.pleo.io/deprecation/legacy-export-api/migrate-from-v1-to-v3.md), [v0 to v3](https://developers.pleo.io/deprecation/legacy-export-api/migrate-from-v0-to-v3.md).

### Which Export API migration guide do I use?

Look at the path that your integration calls.

* If it starts with `/v2/`, use [Migrate from Export API v2 to v3](https://developers.pleo.io/deprecation/legacy-export-api/migrate-from-v2-to-v3.md).
* If it starts with `/v1/`, use [Migrate from Export API v1 to v3](https://developers.pleo.io/deprecation/legacy-export-api/migrate-from-v1-to-v3.md).
* If it starts with `/v0/`, use [Migrate from Export API v0 to v3](https://developers.pleo.io/deprecation/legacy-export-api/migrate-from-v0-to-v3.md).

Each guide goes directly to Export API (v3). Do not migrate through an intermediate version. The export workflow does not change.

### What changes in every version of the migration?

Make these changes in every guide:

* Change the version in the path to `/v3/`.
* Replace the `status` query parameter of `GET /v3/export-jobs` with `statuses`.
* Replace `teamCode` with `team.code`.
* Ignore fields that you do not know, and accept values that you do not know for fields such as `type`, `status` and `failureReasonType`.
* Map contra accounts before you create an Export Job.

### What are contra accounts, and why does v3 fail without them?

* Contra accounts are new in v3. Map them for the company before you create an Export Job.
* If they are missing, `POST /v3/export-jobs` and `GET /v3/export-items` fail with the `MISSING_CONTRA_ACCOUNTS` error.

See [How to Resolve MISSING\_CONTRA\_ACCOUNTS](https://developers.pleo.io/docs/current/how-tos/accounting-integrations/how-to-resolve-missing-contra-accounts.md).

### Does the Export Item payload change in v3?

It depends on your current version.

* **From v2:** No. The structure is the same and v3 adds fields.
* **From v1:** The objects that v1 already had stay the same. v3 adds the objects `vendor`, `bookkeeping`, `servicePeriod` and `contraAccount`.
* **From v0:** Yes. v3 groups related data into named objects such as `team`, `additionalInformation`, `vendor`, `bookkeeping` and `servicePeriod`.
* **From v0 only:** The `metadata` object is removed and its data is in `additionalInformation`.

v3 may add more fields over time. See [Get Export Items](https://developers.pleo.io/reference/export-api/export-items-v3/get-export-items.md) for the full list.

Check your parsing before you switch.

***

## Legacy Receipt API

Migration guides: [Overview](https://developers.pleo.io/deprecation/legacy-receipt-api/overview.md), [Export API (v3)](https://developers.pleo.io/deprecation/legacy-receipt-api/migrate-to-export-api.md), [Accounting Entries API](https://developers.pleo.io/deprecation/legacy-receipt-api/migrate-to-accounting-entries-api.md).

### Which API replaces the legacy Receipt API?

It depends on whether you run an export.

* If you book expenses in an Accounting System, use the Export API (v3). It provides receipts as attachments on Export Items.
* To get receipts outside an Export Job, use the Accounting Entries API.

The Export API (v3) is not a standalone receipt lookup. To choose, see the [Legacy Receipt API Overview](https://developers.pleo.io/deprecation/legacy-receipt-api/overview.md).

### How do I get receipts with the Export API (v3)?

Follow these steps:

1. Start the Export Job.
2. Fetch its Export Items with `GET /v3/export-items?job_id={jobId}`.
3. Read the `files[]` list on each item and download each file from its `url`.
4. Complete the job after the downloads.

Keep these limits in mind:

* You can only fetch Export Items while the job is `pending` or `in_progress`, so download the files before you complete the job.
* The `url` expires 24 hours after you fetch the items.
* An item has zero, one or several attachments. Each attachment can be up to 30 MB.

### How do I get receipts outside an Export Job?

* Use `GET /v1/accounting-entries/{accountingEntryId}/receipts`. Pass the legacy `expenseId` as the `accountingEntryId`, because both identify the same record.
* To search the receipts of many Accounting Entries in one request, use `POST /v1/accounting-entries/receipts:search`.
* The endpoints return the `ORIGINAL` file by default. For `THUMBNAIL` or `PREVIEW`, set the `file_type` query parameter on the GET endpoint, or `fileType` in the body of the search.
* The receipt `url` expires after 24 hours.

***

## Legacy Tag Groups API

Migration guide: [Tags API](https://developers.pleo.io/deprecation/legacy-tag-groups-api/migrate-to-tags-api.md).

### Which API replaces the legacy Tag Groups API?

The Tags API replaces it.

* `/tag-groups` becomes `/v0/tag-groups`.
* Tags are in `/v0/tag-groups/{groupId}/tags` and `/v0/tags/{tagId}`.
* The legacy API had no company in the request. In the new API, `GET /v0/tag-groups` needs `company_id` or `organization_id`. `POST /v0/tag-groups` and `GET /v0/tags` need `company_id`. Endpoints that use a tag group ID or a tag ID need neither.

### How do updates differ in the Tags API?

The new `PUT` endpoints replace the whole resource. The legacy `PATCH` endpoints changed only the fields that you sent. Send all the required fields on every update:

* **Tag group:** `archived`, `code`, `metadata` and `name`.
* **Tag:** `archived` and `code`.

### How do I archive or delete a tag group or tag?

* Archive with a `PUT` request and `"archived": true`.
* Delete with `DELETE`. The legacy `archive` query parameter on `DELETE /tag-groups/{tagGroupId}` chose between the two.
* Tags Sync archives tag groups and tags and does not delete them.
* The legacy `archived` and `hidden` query parameters returned only archived or hidden records when set to `true`. The new `include_archived` parameter adds archived records to the active ones. To get only archived records, set `include_archived` to `true` and filter the response by `archived: true`.

### What identifier does the Tags API use to match tag groups and tags?

* Every tag group and tag now has a `code`, which is the identifier from the external system.
* Tags Sync matches on `code` and ignores case.
* A company can have no more than five active tag groups.

***

## Legacy Tax Code API

Migration guides: [Overview](https://developers.pleo.io/deprecation/legacy-tax-code-api/overview.md), [Tax Code API](https://developers.pleo.io/deprecation/legacy-tax-code-api/migrate-to-tax-code-api.md), [Export API (v3)](https://developers.pleo.io/deprecation/legacy-tax-code-api/migrate-to-export-api.md).

### 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`.

### 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.

***

## Related Reading

* [API Deprecation Notice](https://developers.pleo.io/deprecation/overview.md)
* [Migration Catalogue](https://developers.pleo.io/deprecation/migration-guides.md)
