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

# Chart of Accounts Sync Overview

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

subgraph AS["Accounting System / ERP"]
    source["Chart of Accounts"]
end

subgraph Integration["Chart of Accounts Sync Integration"]
    sync["Sync Logic + Reconciliation Engine"]
end

subgraph Pleo["Pleo"]
    target["Accounts"]
end

AS -.-> Integration
Integration -->|"Pleo Chart of Accounts 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>;

**Chart of Accounts Sync** is how Pleo keeps its Chart of Accounts up to date by synchronising account records from an external Accounting System into Pleo.

It ensures bookkeepers always have an accurate, current list of accounts to reference when mapping expense categories to accounts in Pleo, without having to manually maintain those accounts.

## Purpose of Chart of Accounts Sync

Chart of Accounts Sync exists to:

* Remove the need to manually create or maintain accounts in Pleo
* Reflect the current state of the Chart of Accounts from the Accounting System
* Enable accurate bookkeeping by ensuring expense categories map to the correct accounts
* Keep account data synchronised between systems

## Core Concept

Chart of Accounts Sync is based on a direct mapping between systems:

| Accounting System          | Pleo                        |
| -------------------------- | --------------------------- |
| Chart of Accounts entry    | Account                     |
| Account identifier         | Account `externalId`        |
| Account number             | Account `code`              |
| Account name               | Account `name`              |
| Default tax code reference | Account `taxCodeExternalId` |

For detailed field-level mapping, see [Chart of Accounts Sync Data Mapping](/docs/current/integration-design/accounting-integrations/imports/accounts/integration-design-accounts-data-mapping).

### How Accounts Are Used in Pleo

Accounts synced into Pleo are not assigned directly to expenses. Instead, bookkeepers map each expense category to an account in the Pleo Web App. When a spender assigns a category to an expense, the account mapped to that category is what gets used for bookkeeping and exported to the Accounting System.

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

    AS_in["Accounting System<br>Chart of Accounts"]
    Spender["Spender"]

    subgraph integration["Integration"]
        sync["Chart of Accounts Sync"]
        export["Export API"]
    end

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

    AS_out["Accounting System"]

    AS_in --> sync
    sync -->|"accounts synced in"| coa
    coa -->|"bookkeeper maps<br>accounts to categories"| categories
    categories --> expense_export
    Spender -->|"assigns category<br>via Pleo app"| expense_export
    expense_export --> export
    export -->|"exported with<br>mapped account"| AS_out

    style AS_in 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 Chart of Accounts:** the source of account data
2. **Pleo Chart of Accounts:** accounts are synced in and kept up to date via Chart of Accounts Sync
3. **Pleo Categories:** bookkeepers map each category to an account in the Pleo Web App
4. **Expenses:** when a spender selects a category on an expense, the mapped account is used for bookkeeping

This is why keeping Pleo's Chart of Accounts accurate matters: if the account data is stale or incorrect, categories may reference the wrong accounts when expenses are exported.

### What Happens in Pleo Once Synchronised

* Each active account from the Accounting System is reflected as an account in Pleo
* Accounts are available for bookkeepers to assign to expense categories
* If an account's name or code changes in the Accounting System, it is updated in Pleo on the next sync
* Accounts no longer active in the Accounting System are archived in Pleo

This ensures expense categories always reference the correct accounts without requiring manual input.

<RememberCallout title="Remember">
  If the Accounting System has a default tax code per account, that identifier can be stored in Pleo via `taxCodeExternalId`. This is a reference only. Pleo does not automatically link it to a Tax Code in Pleo, apply it to expenses, or update the default tax code on any category mapped to the account.
</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 account data                             |
| Structural Mapping        | Accounts map directly from the Accounting System into Pleo                                        |
| Identity Model            | Matching is performed using `externalId`, not account name or code                                |
| Non-Destructive Behaviour | Accounts 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 accounts from the Chart of Accounts                     |
| Sync Execution | Execute reconciliation operations in Pleo via the Chart of Accounts API |
| Scheduling     | Define and execute sync schedule (including optional manual triggers)   |

### Pleo Responsibilities

Pleo provides storage, user experience, and downstream usage of accounts.

| Area             | Responsibility                                             |
| ---------------- | ---------------------------------------------------------- |
| Data Storage     | Store accounts                                             |
| User Interface   | Display accounts for category assignment                   |
| Category Mapping | Allow bookkeepers to assign accounts to expense categories |
| Data Retention   | Retain archived accounts for historical consistency        |

## High-Level Process

```mermaid theme={null}
%%{init: {"themeVariables": {"fontSize": "12px"}}}%%
flowchart TD
    A[Accounting System<br>Chart of Accounts]
    B[Step 1:<br>Fetch Active Accounts from AS]
    C[Step 2:<br>Fetch Accounts from Pleo]
    D[Step 3:<br>Reconcile by externalId]
    E[Pleo<br>Accounts]
    F[Category Assignment]

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

    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
    style F white-space:normal
```

Chart of Accounts Sync runs as a single reconciliation process:

1. **Fetch active accounts** from the Accounting System
2. **Fetch accounts from Pleo** (active and archived)
3. **Reconcile:** match by `externalId` 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

Chart of Accounts Sync is one-way only:

<CoASyncDirectionDiagram />

* 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 [Chart of Accounts Sync Periodicity and Scheduling](/docs/current/integration-design/accounting-integrations/imports/accounts/integration-design-accounts-periodicity).

***

## Related Reading

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

***