Skip to main content
This guide is for partners who used the legacy Tax Code API 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 instead.

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

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.

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.

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

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.
To choose, see the Legacy Tax Code API Overview.

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.