New to the Export API (v3)?
Export Workflow Guide
End-to-end walkthrough of the Export API (v3) integration model.
Data Mapping
How to map Export Item fields, including the Tax Code and VAT, to your Accounting System.
API Scopes
Required scopes:
export-jobs:write, export-jobs:read, export-items:read.OAuth Guide
End-to-end OAuth 2.0 workflow guide for Pleo integrations.
Standalone API Key Guide
End-to-end guide for authenticating with standalone API keys.
Migrate from the Expenses API
The full export steps for integrations that used the Expenses API.
What Changes in Your Integration
With the legacy APIs, an expense only held ataxCodeId. 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.
Reading Tax Codes from Export Items
- Detect a
pendingExport Job and start it withPOST /v3/export-job-eventsand"event": "started". The Export Job is nowin_progress. - Fetch the Export Items with
GET /v3/export-items?job_id={jobId}. This endpoint is paginated. Thelimitparameter sets the page size only. To read every page, passpagination.endCursorasafterin the next request untilpagination.hasNextPageisfalse. - Read the
taxobject on each Accounting Entry line, inaccountingEntryLines[]. - Match
tax.codeto the Tax Code in the Accounting System, and use it when you create the entry.
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.
VAT Amounts
The Export API (v3) also returns the taxamount 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.
Field Mapping
The table below maps the fields of the legacy Tax Code API response to the fields of thetax 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
FAQs
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 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.