> ## Documentation Index
> Fetch the complete documentation index at: https://developers.pleo.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Tax Sync Workflow Guide

export const CreateUpdateArchiveTaxCodesDiagram = () => {
  const diagram = `
%%{init: {"themeVariables": {"fontSize": "18px"}}}%%
flowchart LR
    S1["1. Create Tax Codes for New AS Entries"] --> S2["2. Unarchive or Update Existing Tax Codes"] --> S3["3. Archive Tax Codes with No Matching AS Entry"] --> S4["4. Handle Duplicate Codes in Pleo"]

click S1 "#1-create-tax-codes-for-new-as-entries"
click S2 "#2-unarchive-or-update-existing-tax-codes"
click S3 "#3-archive-tax-codes-with-no-matching-as-entry"
click S4 "#4-handle-duplicate-codes-in-pleo"

style S1 white-space:normal
style S2 white-space:normal
style S3 white-space:normal
style S4 white-space:normal
`;
  return <Mermaid chart={diagram} />;
};

export const FetchAndMatchTaxCodesDiagram = () => {
  const diagram = `
%%{init: {"themeVariables": {"fontSize": "18px"}}}%%
flowchart LR
    S1["1. Fetch Relevant Active Tax Codes from AS"] --> S2["2. Fetch All Tax Codes from Pleo"] --> S3["3. Match by code<br><br>"] --> S4["Create, Update,\nand Archive Tax Codes"]

click S1 "#1-retrieve-relevant-active-tax-codes-from-the-accounting-system"
click S2 "#2-retrieve-all-tax-codes-from-pleo"
click S3 "#3-match-as-tax-codes-to-pleo-tax-codes-by-code"

style S1 white-space:normal
style S2 white-space:normal
style S3 white-space:normal
style S4 white-space:normal,stroke-dasharray:5 5
`;
  return <Mermaid chart={diagram} />;
};

export const TaxSyncOverviewDiagram = () => {
  const diagram = `
%%{init: {"themeVariables": {"fontSize": "12px"}}}%%
flowchart LR

subgraph AS["Accounting System"]
    source["Tax Codes"]
end

subgraph Pleo["Pleo APIs"]
    A["1. Fetch and Match Tax Codes"]
    B["2. Create, Update, and Archive Tax Codes"]
    A --> B
end

source --> A

click A "#1-fetch-and-match-tax-codes"
click B "#2-create-update-and-archive-tax-codes"

style A white-space:normal
style B white-space:normal
style source white-space:normal

style AS fill:none,stroke:#000000
style Pleo fill:none,stroke:#000000
`;
  return <Mermaid chart={diagram} />;
};

export const WhatComesNext = ({children, href}) => <div className="mt-4">
    <a href={href} className="
        inline-flex items-center justify-center
        rounded-full
        bg-black text-white dark:bg-[#1f262b]
        px-5 py-2.5 text-sm font-medium
        no-underline border-0
        hover:bg-[#ffe6ea] dark:hover:bg-[#2b1f23]
        hover:text-black
        transition-colors
      ">
      {children} →
    </a>
  </div>;

export const RecommendedCallout = ({title, children, icon = "⭐"}) => <div style={{
  backgroundColor: 'var(--recommended-bg)',
  borderLeft: '4px solid #f8f1ac',
  borderRadius: '10px',
  padding: '18px 22px',
  marginBottom: '20px',
  boxShadow: '1px 1px 3px rgba(0,0,0,0.06)'
}}>
    <div style={{
  display: 'flex',
  alignItems: 'flex-start',
  gap: '14px'
}}>
      <span style={{
  fontSize: '22px',
  lineHeight: '1',
  flexShrink: 0
}}>
        {icon}
      </span>
      <div>
        {title && <div style={{
  fontSize: '16px',
  fontWeight: 600,
  color: 'var(--recommended-title)',
  marginBottom: '6px'
}}>
            {title}
          </div>}
        <div style={{
  fontSize: '14px',
  lineHeight: 1.65
}}>
          {children}
        </div>
      </div>
    </div>
  </div>;

<RecommendedCallout title="Recommended Workflow">
  This guide covers [Integration Level 3](/docs/current/getting-started/accounting-integrations-overview), which enables syncing Tax Codes from your Accounting System (AS) into Pleo. It builds on Level 3 (Chart of Accounts Sync) and ensures bookkeepers can assign the correct tax codes to expenses before export.
</RecommendedCallout>

## 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](/docs/current/integration-design/auth/integration-design-auth-overview#authentication-policy-overview) methods.
* The [Tax Sync](/docs/current/platform/accounting-integrations/imports/tax-codes/tax-sync-overview) 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.

<TaxSyncOverviewDiagram />

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.

| Tax Code (AS)          | AS Status | Tax Code (Pleo)        | Pleo Status    | Desired Pleo State   |
| ---------------------- | --------- | ---------------------- | -------------- | -------------------- |
| VAT20 - Standard (20%) | Active    | VAT20 - Standard (20%) | Active         | Active (no change)   |
| VAT5 - Reduced (5%)    | Active    | VAT5 - Reduced (5%)    | Archived       | Unarchived           |
| VAT0 - Zero Rated (0%) | Active    | —                      | Does not exist | Created              |
| REV - Reverse Charge   | Active    | REV - Reverse Charge   | Active         | Updated to match AS  |
| —                      | —         | EXEMPT - Exempt        | Active         | Archived (not in AS) |

The two steps progress as follows:

| Step                                     | Integration action                                           | Outcome                                              |
| ---------------------------------------- | ------------------------------------------------------------ | ---------------------------------------------------- |
| 1. Fetch and Match Tax Codes             | Fetches tax codes from AS and Pleo, matches by `code`        | Each tax code is paired with a required action       |
| 2. Create, Update, and Archive Tax Codes | Creates, updates, unarchives, and archives Tax Codes in Pleo | Pleo reflects the current active, relevant tax codes |

***

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

<FetchAndMatchTaxCodesDiagram />

#### 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](/docs/current/integration-design/accounting-integrations/imports/tax-codes/integration-design-tax-sync) 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.

<WhatComesNext href="/docs/current/how-tos/accounting-integrations/imports/tax-codes/how-to-fetch-and-match-tax-codes">
  How to Fetch and Match Tax Codes
</WhatComesNext>

***

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

<CreateUpdateArchiveTaxCodesDiagram />

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](/docs/current/integration-design/accounting-integrations/imports/tax-codes/integration-design-tax-sync) 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.

<WhatComesNext href="/docs/current/how-tos/accounting-integrations/imports/tax-codes/how-to-create-update-archive-tax-codes">
  How to Create, Update, and Archive Tax Codes
</WhatComesNext>

***

## 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](/docs/current/getting-started/accounting-integrations-overview): Sync vendors between Pleo and your Accounting System (Level 4).

***

## Related Reading

* [Integration Design: Tax Sync Overview](/docs/current/integration-design/accounting-integrations/imports/tax-codes/integration-design-tax-sync-overview)
* [Platform Capabilities: Tax Sync](/docs/current/platform/accounting-integrations/imports/tax-codes/tax-sync-overview)

***