Skip to main content
This guide is for partners who used the legacy Tax Code API to read the Tax Codes of a company. If you used it to look up the Tax Codes of expenses that you book in an Accounting System, see Migrate to the New Export API (v3) instead. The legacy Tax Code API has been deprecated. This guide covers how to migrate to the new Tax Code API.

New to the New Tax Code API?

API Overview

What a Tax Code is and how the new API is structured.

API Scopes

Required scopes: tax-codes:read and tax-codes:write.

Tax Sync Overview

How Tax Codes are kept in step with an Accounting System, and how Tax Codes are used in Pleo.

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

Getting Started

You need API credentials with the tax-codes:read scope to read Tax Codes. You also need the tax-codes:write scope if you create or update Tax Codes. The new Tax Code API takes the company in different places by endpoint. POST /v0/tax-codes:search takes the company_id query parameter. Create and update requests take companyId in the JSON body. If you manage more than one company, handle each company on its own. For more information, see Multi-Entity and API Scope.

Endpoint Mapping

The table below maps the endpoints of the legacy Tax Code API to the endpoints of the new Tax Code API.
  • — : endpoint is not available in the legacy Tax Code API

Key Differences

  • The legacy Tax Code API could only read Tax Codes. The new Tax Code API can also create, update and delete them. To keep Tax Codes in step with an Accounting System, see the Tax Sync Workflow Guide. Tax Sync archives Tax Codes and does not delete them.
  • The legacy GET /tax-codes endpoint returned a taxCodes list. The new search endpoint returns a data list and a pagination object. Use the limit, after, before and offset query parameters to page through the results. You can sort with sorting_keys and sorting_order.
  • The legacy hidden query parameter included hidden Tax Codes. The new search endpoint returns both archived and active Tax Codes unless you set archived in the request body. To exclude archived Tax Codes, send "archived": false.
  • The legacy enabled field is replaced by archived. The value is the opposite. A Tax Code that was enabled: true is now archived: false.
  • The legacy type values were NORMAL and REVERSE. The new type values are inclusive, exclusive and reverse. Map NORMAL to inclusive and REVERSE to reverse. Do not map either legacy value to exclusive. The exclusive value is in the API specification, but it is not currently supported.
  • The new search endpoint can also filter by type and taxCodeIds.
  • The legacy force query parameter has no equivalent in the new Tax Code API.
  • The legacy response did not include the company. Each new Tax Code has a companyId.
  • The new Tax Code API returns rate as a decimal, for example 0.20 for a 20% tax rate.

Field Mapping

The table below maps the fields of the legacy Tax Code API response to the fields of the new Tax Code object.
  • — : field is not available on the legacy model
  • * : data is the same but represented differently

Example

The legacy request returns the Tax Codes of the company:
The new request needs the company_id query parameter. To return only active Tax Codes, send "archived": false in the request body.
The response contains the Tax Codes in data and the paging details in pagination.

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