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

General

Deadlines, communications and other questions that apply to every migration.

Legacy Accounts API

Moving accounts and categories to the Chart of Accounts API and the Bookkeeping Categories API.

Legacy Company Balance API

Moving the company balance to the Company Balance API.

Legacy Expense API

Moving expense exports to the Export API and expense data to the Accounting Entries API.

Legacy Export API

Choosing the right guide and moving from Export API v0, v1 or v2 to v3.

Legacy Receipt API

Getting receipts with the Export API or the Accounting Entries API.

Legacy Tag Groups API

Moving tag groups to the Tags API.

Legacy Tax Code API

Moving tax codes to the Tax Code API and the Export API.

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 and v1 to v3.

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.

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 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 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), 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.

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

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.

Legacy Accounts API

Migration guides: Overview, Chart of Accounts API, Bookkeeping Categories API.

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.

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.

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.

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, Export API (v3), Accounting Entries API.

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.

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 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, v2 to v3, v1 to v3, v0 to v3.

Which Export API migration guide do I use?

Look at the path that your integration calls.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.

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 for the full list.Check your parsing before you switch.

Legacy Receipt API

Migration guides: Overview, Export API (v3), Accounting Entries API.

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.

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.

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, Tax Code API, Export API (v3).

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.

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.