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 thetax-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-codesendpoint returned ataxCodeslist. The new search endpoint returns adatalist and apaginationobject. Use thelimit,after,beforeandoffsetquery parameters to page through the results. You can sort withsorting_keysandsorting_order. - The legacy
hiddenquery parameter included hidden Tax Codes. The new search endpoint returns both archived and active Tax Codes unless you setarchivedin the request body. To exclude archived Tax Codes, send"archived": false. - The legacy
enabledfield is replaced byarchived. The value is the opposite. A Tax Code that wasenabled: trueis nowarchived: false. - The legacy
typevalues wereNORMALandREVERSE. The newtypevalues areinclusive,exclusiveandreverse. MapNORMALtoinclusiveandREVERSEtoreverse. Do not map either legacy value toexclusive. Theexclusivevalue is in the API specification, but it is not currently supported. - The new search endpoint can also filter by
typeandtaxCodeIds. - The legacy
forcequery 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
rateas a decimal, for example0.20for 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:company_id query parameter. To return only active Tax Codes, send "archived": false in the request body.
- OAuth 2.0
- API Key
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.
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.