Tax Sync Workflow Guide

​

What You’ll Have Built

After implementing this workflow:

• Active, relevant tax codes from the AS are reflected as Tax Codes in Pleo.
• Tax Codes are automatically kept up to date on a scheduled basis.
• Bookkeepers can assign current, accurate tax codes to expenses in Pleo.
• The integration aligns with Pleo’s Tax Sync guarantees and matching model.

​

Who This Guide Is For

This guide is intended for:

• Integration developers
• Solution architects
• Accounting platform integrators

It focuses on workflow understanding, not implementation details.

​

Before You Start

You should be familiar with:

• Pleo’s supported authentication methods.
• The Tax Sync platform capabilities page.

​

Tax Sync Workflow Overview

Tax codes in the AS are the definitive list of tax rates used to classify expenses for reporting and compliance. Each tax code has a code (the identifier visible across systems), a name, a rate, and a type. Tax Sync copies this structure into Pleo. The Accounting System is the source of truth; the integration’s role is to keep Pleo’s Tax Codes aligned with the current state of the AS so bookkeepers always have accurate, up-to-date options when assigning tax codes to expenses. Unlike Tags Sync, Tax Sync does not have a user-driven selection step. All relevant active tax codes from the AS are synchronised into Pleo after filtering out irrelevant types (such as Sales VAT) and inactive codes. The how-to articles in this section use a consistent example to illustrate each step. The table below shows the starting state in both systems before the sync runs. The two steps progress as follows:

---

​

Steps

​

1. Fetch and Match Tax Codes

​

Purpose

This step runs at the start of every Tax Sync cycle. The integration retrieves relevant active tax codes from the AS and all Tax Codes from Pleo (active and archived), then matches them using the code field to determine what action is needed for each tax code.

​

Input

• Relevant active tax codes from the AS (filtered to exclude Sales VAT, blocked, or inactive codes)
• Active and archived Tax Codes from Pleo. Archived Tax Codes are included so they can be unarchived rather than duplicated if a tax code becomes active in the AS again.

​

Workflow Process

The integration retrieves and filters AS tax codes, then retrieves all Pleo Tax Codes. It matches every AS tax code against Pleo Tax Codes by code (case insensitive) and determines the required action for each.

​

Output

• Each AS tax code matched to a Pleo Tax Code (or identified as new)
• Each Pleo Tax Code identified as requiring creation, unarchiving, updating, or no action
• Active Pleo Tax Codes with no AS match flagged for archiving

​

Why It Matters

The matching step is the foundation of the reconciliation. Accurate matching by code ensures tax codes are updated rather than duplicated, and that tax codes removed from the AS are archived rather than left stale in Pleo.

​

Integration Design

If you’re an integration developer or architect, read the Sync Tax Codes integration design doc before implementing this step. It covers the matching rules, type mapping, duplicate handling behaviour, and how the sync handles each reconciliation outcome.

​

Step-by-Step Instructions

When you’re ready to start implementing, follow the step-by-step instructions in the accompanying how-to article.

---

​

2. Create, Update, and Archive Tax Codes

​

Purpose

This step runs immediately after the matching step. For each tax code requiring action, the integration creates, updates, unarchives, or archives the corresponding Tax Code in Pleo. After all AS tax codes are processed, any active Pleo Tax Code with no matching AS tax code is archived.

​

Input

• Relevant active tax codes from the AS (used to drive create, update, and unarchive operations)
• The matched tax code set from Step 1, identifying which Pleo Tax Codes require action and which active Pleo Tax Codes have no AS match

​

Workflow Process

For each tax code identified in Step 1:

• Create new Tax Codes for AS tax codes with no existing match in Pleo
• Unarchive Tax Codes where an active AS tax code matches an archived Pleo Tax Code
• Update Tax Code names, rates, and types where they differ from the current AS
• Archive active Tax Codes where their AS tax code is no longer active
• Deduplicate if two Pleo Tax Codes share the same code: retain the one matching the AS rate, archive the other

​

Output

• Tax Codes created for AS tax codes with no existing match in Pleo
• Archived Tax Codes unarchived where an active AS tax code matches
• Tax Code names, rates, and types updated where they differ from the current AS
• Active Tax Codes archived where their AS tax code is no longer active

​

Why It Matters

These write operations bring Pleo’s Tax Codes into alignment with the AS. Without them, the tax code list in Pleo will drift out of date, causing bookkeepers to assign incorrect tax codes to expenses before export.

​

Integration Design

If you’re an integration developer or architect, read the Sync Tax Codes integration design doc before implementing this step. It covers the API operations, request and response structure, and the data mapping requirements.

​

Step-by-Step Instructions

When you’re ready to start implementing, follow the step-by-step instructions in the accompanying how-to article.

---

​

What Comes Next?

Once Tax Sync is live, bookkeepers can assign the synced tax codes to expenses in Pleo before export. To extend your integration further:

• Vendor Sync: Sync vendors between Pleo and your Accounting System (Level 4).

---

​

Related Reading

• Integration Design: Tax Sync Overview
• Platform Capabilities: Tax Sync

---