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 withPOST /v1/chart-of-accounts. - The Bookkeeping Categories API replaces
/account-groups, for example withPOST /v1/bookkeeping-category-groups.
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.externalIdis 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 indata.failed[]withEXTERNAL_ID_ALREADY_EXISTS, and the other valid items are still created. - The legacy
accountNumberis nowcode.
Should I delete an account in production?
No. Archive it instead.
- Archive with a
PUTrequest and"archived": true. The legacyhiddenfield is nowarchived. - 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
DELETEonly to remove test accounts in staging. - Chart of Accounts Sync archives accounts and does not delete them.
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 incategoryGroupIdand the account inaccountId. - The update request needs
archived,nameandcategoryGroupId, 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:readscope. - The legacy endpoint used the company of the bearer token. The new endpoint takes an explicit
companyIdin the path. - It returns
404if the company is not found,410if the company accounts are closed, and502if 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. Thevalueis 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.
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:- Start the job with
POST /v3/export-job-eventsand"event": "started". - Fetch the data to export with
GET /v3/export-items?job_id={jobId}. - Fetch the export tracking state with
GET /v3/export-jobs/{jobId}/items. - Mark every item
in_progresswithPUT /v3/export-jobs/{jobId}/items. Do not skip this step. If you do, the expenses can stay in the Queued tab. - 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 thanPUT /v1/expenses. - 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.
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:readscope. - 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.
- If it starts with
/v2/, use Migrate from Export API v2 to v3. - If it starts with
/v1/, use Migrate from Export API v1 to v3. - If it starts with
/v0/, use Migrate from Export API v0 to v3.
What changes in every version of the migration?
Make these changes in every guide:
- Change the version in the path to
/v3/. - Replace the
statusquery parameter ofGET /v3/export-jobswithstatuses. - Replace
teamCodewithteam.code. - Ignore fields that you do not know, and accept values that you do not know for fields such as
type,statusandfailureReasonType. - 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-jobsandGET /v3/export-itemsfail with theMISSING_CONTRA_ACCOUNTSerror.
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,servicePeriodandcontraAccount. - From v0: Yes. v3 groups related data into named objects such as
team,additionalInformation,vendor,bookkeepingandservicePeriod. - From v0 only: The
metadataobject is removed and its data is inadditionalInformation.
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.
How do I get receipts with the Export API (v3)?
Follow these steps:
- Start the Export Job.
- Fetch its Export Items with
GET /v3/export-items?job_id={jobId}. - Read the
files[]list on each item and download each file from itsurl. - Complete the job after the downloads.
- You can only fetch Export Items while the job is
pendingorin_progress, so download the files before you complete the job. - The
urlexpires 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 legacyexpenseIdas theaccountingEntryId, 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
ORIGINALfile by default. ForTHUMBNAILorPREVIEW, set thefile_typequery parameter on the GET endpoint, orfileTypein the body of the search. - The receipt
urlexpires 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-groupsbecomes/v0/tag-groups.- Tags are in
/v0/tag-groups/{groupId}/tagsand/v0/tags/{tagId}. - The legacy API had no company in the request. In the new API,
GET /v0/tag-groupsneedscompany_idororganization_id.POST /v0/tag-groupsandGET /v0/tagsneedcompany_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,metadataandname. - Tag:
archivedandcode.
How do I archive or delete a tag group or tag?
- Archive with a
PUTrequest and"archived": true. - Delete with
DELETE. The legacyarchivequery parameter onDELETE /tag-groups/{tagGroupId}chose between the two. - Tags Sync archives tag groups and tags and does not delete them.
- The legacy
archivedandhiddenquery parameters returned only archived or hidden records when set totrue. The newinclude_archivedparameter adds archived records to the active ones. To get only archived records, setinclude_archivedtotrueand filter the response byarchived: 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
codeand 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.
How do I map the legacy Tax Code fields to the new Tax Code API?
- Map the legacy type
NORMALtoinclusiveandREVERSEtoreverse. Do not map either toexclusive, which is in the specification but is not currently supported. - The legacy
enabledfield is nowarchived, and the value is the opposite. - The new
rateis a decimal, for example0.20for 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
taxobject can benull, 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_unknownfailure reason.