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

export const TaxSyncDirectionDiagram = () => {
  const diagram = `
%%{init: {"themeVariables": {"fontSize": "18px"}}}%%
flowchart RL

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

subgraph Integration["Tax Sync Integration"]
    sync["Sync Logic + Reconciliation Engine"]
end

subgraph Pleo["Pleo"]
    target["Tax Codes"]
end

AS -.-> Integration
Integration -->|"Pleo Tax Codes API"| Pleo

style source white-space:normal
style sync white-space:normal
style target white-space:normal
style AS fill:none,stroke:#000000
style Integration fill:none,stroke:#000000
style Pleo fill:none,stroke:#000000
`;
  return <Mermaid chart={diagram} />;
};

export const RememberCallout = ({title, children, icon = "🪢"}) => <div style={{
  backgroundColor: 'var(--recommended-bg)',
  borderLeft: '4px solid #f63b92',
  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>;

**Tax Sync** is how Pleo keeps its Tax Codes up to date by synchronising tax code records from an external Accounting System into Pleo.

It ensures bookkeepers always have an accurate, current list of tax codes to reference when assigning tax codes to expenses in Pleo, without having to manually maintain those codes.

## Purpose of Tax Sync

Tax Sync exists to:

* Remove the need to manually create or maintain Tax Codes in Pleo
* Reflect the current state of active tax codes from the Accounting System
* Enable accurate bookkeeping by ensuring expenses carry the correct tax codes before export
* Keep tax code data synchronised between systems

## Core Concept

Tax Sync is based on a direct mapping between systems:

| Accounting System   | Pleo                       |
| ------------------- | -------------------------- |
| Tax code entry      | Tax Code                   |
| Tax code identifier | Tax Code `code`            |
| Tax code name       | Tax Code `name`            |
| Tax rate            | Tax Code `rate`            |
| Reverse tax         | Tax Code `type: reverse`   |
| All other taxes     | Tax Code `type: inclusive` |

For detailed field-level mapping, see [Tax Sync Data Mapping](/docs/current/integration-design/accounting-integrations/imports/tax-codes/integration-design-tax-sync-data-mapping).

### How Tax Codes Are Used in Pleo

Tax Sync works alongside Chart of Accounts Sync as part of Level 3. Both must be in place for the full tax assignment flow to work: accounts are synced and mapped to categories, tax codes are synced, and the bookkeeper then sets a default tax code on each category in the Pleo Web App. From that point, when a spender selects a category on an expense, the default tax code is automatically applied.

```mermaid theme={null}
%%{init: {"themeVariables": {"fontSize": "12px"}}}%%
flowchart TD

    AS_tax["Accounting System<br>Tax Codes"]
    AS_coa["Accounting System<br>Chart of Accounts"]
    Spender["Spender"]

    subgraph integration["Integration"]
        tax_sync["Tax Sync"]
        coa_sync["Chart of Accounts Sync"]
        export["Export API"]
    end

    subgraph pleo["Pleo"]
        tax["Tax Codes"]
        coa["Chart of Accounts"]
        categories["Categories"]
        expense["Expense"]
        expense_export["Expense Export"]
    end

    AS_out["Accounting System"]

    AS_tax --> tax_sync
    tax_sync -->|"tax codes synced in"| tax
    AS_coa --> coa_sync
    coa_sync -->|"accounts synced in"| coa
    coa -->|"bookkeeper maps<br>accounts to categories"| categories
    tax -->|"bookkeeper sets default<br>tax code on category<br>(Pleo Web App)"| categories
    Spender -->|"submits expense,<br>selects category"| expense
    categories -->|"default tax code<br>auto-selected"| expense
    expense -->|"bookkeeper confirms<br>or overrides"| expense_export
    expense_export --> export
    export -->|"exported with<br>tax code"| AS_out

    style AS_tax fill:none,stroke:#000000
    style AS_coa fill:none,stroke:#000000
    style AS_out fill:none,stroke:#000000
    style Spender fill:none,stroke:#000000
    style integration fill:none,stroke:#000000
    style pleo fill:none,stroke:#000000
```

The full chain is:

1. **Accounting System Tax Codes:** the source of tax code data, synced into Pleo via Tax Sync
2. **Accounting System Chart of Accounts:** accounts are synced into Pleo via Chart of Accounts Sync and mapped to categories by the bookkeeper
3. **Pleo Categories:** the bookkeeper sets a default tax code on each category in the Pleo Web App
4. **Expenses:** when a user selects a category, the default tax code is auto-selected; the bookkeeper confirms or overrides before export
5. **Export:** the expense is exported to the Accounting System with the assigned tax code

<RememberCallout title="Remember">
  Setting a default tax code on a category must be done explicitly by the bookkeeper in the Pleo Web App. It is not set automatically by Tax Sync or Chart of Accounts Sync.
</RememberCallout>

This is why keeping Pleo's Tax Codes accurate matters: if the tax code data is stale or incorrect, expenses may carry the wrong tax codes when exported.

### What Happens in Pleo Once Synchronised

* Each active, relevant tax code from the Accounting System is reflected as a Tax Code in Pleo
* Tax Codes are available for bookkeepers to assign to expenses
* If a tax code's name or rate changes in the Accounting System, it is updated in Pleo on the next sync
* Tax Codes no longer active in the Accounting System are archived in Pleo

This ensures expenses always reference the correct tax codes without requiring manual input.

<RememberCallout title="Remember">
  Only tax codes relevant to expense management are synced. Tax codes not relevant to expense bookkeeping (such as Sales VAT) and blocked or inactive tax codes are filtered out before syncing.
</RememberCallout>

## System Guarantees

These are invariant rules that always hold true regardless of implementation or sync frequency.

| Guarantee                 | Description                                                                                        |
| ------------------------- | -------------------------------------------------------------------------------------------------- |
| Source of Truth           | The Accounting System is the authoritative source of all tax code data                             |
| Structural Mapping        | Tax Codes map directly from the Accounting System into Pleo                                        |
| Identity Model            | Matching is performed using `code`, not tax code name                                              |
| Non-Destructive Behaviour | Tax Codes are never deleted; they are only archived when no longer active in the Accounting System |
| Idempotency               | Re-running a sync produces the same final state without duplication                                |

## Responsibility Model

### Integrator Responsibilities

The integration is responsible for all synchronisation logic and API interaction.

| Area           | Responsibility                                                                                      |
| -------------- | --------------------------------------------------------------------------------------------------- |
| Connection     | Connect to the Accounting System                                                                    |
| Data Retrieval | Retrieve active, relevant tax codes from the Accounting System                                      |
| Filtering      | Exclude tax codes not relevant to expense management (e.g. Sales VAT) and blocked or inactive codes |
| Sync Execution | Execute reconciliation operations in Pleo via the Tax Codes API                                     |
| Scheduling     | Define and execute sync schedule (including optional manual triggers)                               |

### Pleo Responsibilities

Pleo provides storage, user experience, and downstream usage of tax codes.

| Area           | Responsibility                                       |
| -------------- | ---------------------------------------------------- |
| Data Storage   | Store Tax Codes                                      |
| User Interface | Display Tax Codes for assignment to expenses         |
| Data Retention | Retain archived Tax Codes for historical consistency |

## High-Level Process

```mermaid theme={null}
%%{init: {"themeVariables": {"fontSize": "12px"}}}%%
flowchart TD
    A[Accounting System<br>Tax Codes]
    B[Step 1:<br>Fetch Relevant Active Tax Codes from AS]
    C[Step 2:<br>Fetch Tax Codes from Pleo]
    D[Step 3:<br>Reconcile by code]
    E[Pleo<br>Tax Codes]

    A --> B --> C --> D --> E

    style A white-space:normal
    style B white-space:normal
    style C white-space:normal
    style D white-space:normal
    style E white-space:normal
```

Tax Sync runs as a single reconciliation process:

1. **Fetch relevant active tax codes** from the Accounting System (filtering out irrelevant or inactive codes)
2. **Fetch Tax Codes from Pleo** (active and archived)
3. **Reconcile:** match by `code` and apply create, update, unarchive, or archive operations

Each sync run reconciles Pleo against the current state of the Accounting System.

## Operational Model

### Sync Direction

Tax Sync is one-way only:

<TaxSyncDirectionDiagram />

* The **Accounting System** is the **source of truth**
* The integration synchronises data from the Accounting System into Pleo
* Pleo does not modify Accounting System data

### Operational Constraints

| Constraint           | Description                                                                                                                                         |
| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| Scheduling Ownership | The integration is responsible for defining when sync runs occur, including optional manual triggers                                                |
| Sync Execution       | The integration is responsible for executing sync runs and applying all changes to Pleo via the API                                                 |
| Execution Model      | Each sync run performs full reconciliation of Pleo against the Accounting System                                                                    |
| Rate Limits          | The integration must respect Accounting System API rate limits. See [Pleo API rate limits](/docs/current/authentication/api-base-urls#rate-limits). |
| Concurrency          | Sync runs must not overlap; only one execution may run at a time                                                                                    |

### Sync Lifecycle and Frequency

The integration is responsible for triggering all sync runs. For schedule, frequency, and rate limit details, see [Tax Sync Periodicity and Scheduling](/docs/current/integration-design/accounting-integrations/imports/tax-codes/integration-design-tax-sync-periodicity).

***

## Related Reading

* [Integration Design: Tax Sync Overview](/docs/current/integration-design/accounting-integrations/imports/tax-codes/integration-design-tax-sync-overview)
* [Tax Sync Workflow Guide](/docs/current/guides/accounting-integrations/imports/tax-sync-workflow-guide)
* [Connection and Authorisation Overview](/docs/current/integration-design/auth/integration-design-auth-overview)

***