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

# Tags Sync Overview

export const IntegrationDesignTagsOverviewDiagram = () => {
  const [isDark, setIsDark] = useState(false);
  useEffect(() => {
    const check = () => setIsDark(document.documentElement.classList.contains("dark"));
    check();
    const observer = new MutationObserver(check);
    observer.observe(document.documentElement, {
      attributes: true,
      attributeFilter: ["class"]
    });
    return () => observer.disconnect();
  }, []);
  const nodeFill = isDark ? "#212222" : "#EEF4F4";
  const nodeStroke = isDark ? "#848989" : "#E1E6E6";
  const nodeTextStyle = isDark ? ",color:#EEF4F4" : ",color:#131414";
  const subgraphFill = isDark ? "#131414" : "#ffffff";
  const subgraphStroke = isDark ? "#848989" : "#6B7070";
  const subgraphTextStyle = isDark ? ",color:#EEF4F4" : ",color:#131414";
  const linkStyle = isDark ? "" : "linkStyle default stroke:#848989,stroke-width:1px;";
  const themeVariables = {
    fontSize: "12px",
    ...isDark ? {} : {
      edgeLabelBackground: "#FAFCFC"
    }
  };
  const diagram = `
%%{init: {"themeVariables": ${JSON.stringify(themeVariables)}}}%%
flowchart TD
    subgraph Step1["Step 1: Select Dimensions (first connection only)"]
        A1[Retrieve active Dimensions from AS]
        A2[Match against existing Tag Groups in Pleo]
        A3[Store selection in integration config]
        A1 --> A2 --> A3
    end

    A3 -.->|stored config| B

    subgraph Cycle["Recurring Sync Cycle"]
        B[Sync Triggered]
        C[Load selected Dimensions from config]
        D[Pull Tag Groups and Tags from Pleo]

        subgraph Step2["Step 2: Sync Tag Groups with Dimensions"]
            E[Match by Code]
            F[Create / Unarchive / Preserve]
            G[Archive Unmatched]
            E --> F --> G
        end

        subgraph Step3["Step 3: Sync Tags with Dimension Values"]
            H[Match by Code]
            I[Create / Unarchive / Update / Deduplicate]
            J[Archive Unmatched]
            H --> I --> J
        end

        B --> C --> D --> E
        G --> H
        J --> K[Sync Complete]
    end

    style A1 white-space:normal,fill:${nodeFill},stroke:${nodeStroke}${nodeTextStyle}
    style A2 white-space:normal,fill:${nodeFill},stroke:${nodeStroke}${nodeTextStyle}
    style A3 white-space:normal,fill:${nodeFill},stroke:${nodeStroke}${nodeTextStyle}
    style B white-space:normal,fill:${nodeFill},stroke:${nodeStroke}${nodeTextStyle}
    style C white-space:normal,fill:${nodeFill},stroke:${nodeStroke}${nodeTextStyle}
    style D white-space:normal,fill:${nodeFill},stroke:${nodeStroke}${nodeTextStyle}
    style E white-space:normal,fill:${nodeFill},stroke:${nodeStroke}${nodeTextStyle}
    style F white-space:normal,fill:${nodeFill},stroke:${nodeStroke}${nodeTextStyle}
    style G white-space:normal,fill:${nodeFill},stroke:${nodeStroke}${nodeTextStyle}
    style H white-space:normal,fill:${nodeFill},stroke:${nodeStroke}${nodeTextStyle}
    style I white-space:normal,fill:${nodeFill},stroke:${nodeStroke}${nodeTextStyle}
    style J white-space:normal,fill:${nodeFill},stroke:${nodeStroke}${nodeTextStyle}
    style K white-space:normal,fill:${nodeFill},stroke:${nodeStroke}${nodeTextStyle}

    style Step1 fill:${subgraphFill},stroke:${subgraphStroke}${subgraphTextStyle}
    style Cycle fill:${subgraphFill},stroke:${subgraphStroke}${subgraphTextStyle}
    style Step2 fill:${subgraphFill},stroke:${subgraphStroke}${subgraphTextStyle}
    style Step3 fill:${subgraphFill},stroke:${subgraphStroke}${subgraphTextStyle}
${linkStyle}
`;
  return <Mermaid chart={diagram} />;
};

export const TagsSyncDirectionDiagram = () => {
  const [isDark, setIsDark] = useState(false);
  useEffect(() => {
    const check = () => setIsDark(document.documentElement.classList.contains("dark"));
    check();
    const observer = new MutationObserver(check);
    observer.observe(document.documentElement, {
      attributes: true,
      attributeFilter: ["class"]
    });
    return () => observer.disconnect();
  }, []);
  const nodeFill = isDark ? "#212222" : "#EEF4F4";
  const nodeStroke = isDark ? "#848989" : "#E1E6E6";
  const nodeTextStyle = isDark ? ",color:#EEF4F4" : ",color:#131414";
  const outerFill = "transparent";
  const subgraphFill = isDark ? "#131414" : "#ffffff";
  const subgraphStroke = isDark ? "#848989" : "#6B7070";
  const subgraphTextStyle = isDark ? ",color:#EEF4F4" : ",color:#131414";
  const pleoSubgraphTextStyle = ",color:#FEB6FE";
  const linkStyle = isDark ? "" : "linkStyle default stroke:#848989,stroke-width:1px;";
  const themeVariables = {
    fontSize: "18px",
    ...isDark ? {} : {
      edgeLabelBackground: "#FAFCFC"
    }
  };
  const diagram = `
%%{init: {"themeVariables": ${JSON.stringify(themeVariables)}}}%%
flowchart RL

subgraph AS["Accounting System / ERP"]
    source["Dimensions & Dimension Values"]
end

subgraph Config["Dimension Selection"]
    selection["Selected Dimensions (max 5)"]
end

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

subgraph Pleo["Pleo"]
    target["Tag Groups & Tags"]
end

AS -.-> Config
Config -.-> Integration
Integration -->|"Pleo Tags API"| Pleo

selection -. controls .-> sync

style source white-space:normal,fill:${outerFill},stroke:${nodeStroke}${nodeTextStyle}
style selection white-space:normal,fill:${nodeFill},stroke:${nodeStroke}${nodeTextStyle}
style sync white-space:normal,fill:${nodeFill},stroke:${nodeStroke}${nodeTextStyle}
style target white-space:normal,fill:${nodeFill},stroke:${nodeStroke}${nodeTextStyle}
style AS fill:${subgraphFill},stroke:${subgraphStroke}${subgraphTextStyle}
style Config fill:${subgraphFill},stroke:${subgraphStroke}${subgraphTextStyle}
style Integration fill:${subgraphFill},stroke:${subgraphStroke}${subgraphTextStyle}
style Pleo fill:${subgraphFill},stroke:${subgraphStroke}${pleoSubgraphTextStyle}
${linkStyle}
`;
  return <Mermaid chart={diagram} />;
};

export const RememberCallout = ({title, children}) => <div className="callout-box callout-remember">
    <div className="callout-row">
      <span className="callout-icon">
        <svg width="22" height="22" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 256 256" fill="currentColor"><path d="M229.66,98.34,172.39,155.8c11.46,22.93-1.72,45.86-10.11,57a8,8,0,0,1-12,.83L42.34,105.76A8,8,0,0,1,43,93.85c29.65-23.92,57.4-10,57.4-10l57.27-57.46a8,8,0,0,1,11.31,0L229.66,87A8,8,0,0,1,229.66,98.34Z" opacity="0.2" /><path d="M235.32,81.37,174.63,20.69a16,16,0,0,0-22.63,0L98.37,74.49c-10.66-3.34-35-7.37-60.4,13.14a16,16,0,0,0-1.29,23.78L85,159.71,42.34,202.34a8,8,0,0,0,11.32,11.32L96.29,171l48.29,48.29A16,16,0,0,0,155.9,224c.38,0,.75,0,1.13,0a15.93,15.93,0,0,0,11.64-6.33c19.64-26.1,17.75-47.32,13.19-60L235.33,104A16,16,0,0,0,235.32,81.37ZM224,92.69h0l-57.27,57.46a8,8,0,0,0-1.49,9.22c9.46,18.93-1.8,38.59-9.34,48.62L48,100.08c12.08-9.74,23.64-12.31,32.48-12.31A40.13,40.13,0,0,1,96.81,91a8,8,0,0,0,9.25-1.51L163.32,32,224,92.68Z" /></svg>
      </span>
      <div>
        {title && <div className="callout-title">
            {title}
          </div>}
        <div className="callout-body">
          {children}
        </div>
      </div>
    </div>
  </div>;

This section describes how to implement Tags Sync between an Accounting System and Pleo.

Tags Sync maps Accounting Dimensions to Tag Groups and Dimension Values to Tags in Pleo. Synchronisation is one-way, from the Accounting System into Pleo. The integration is responsible for all sync orchestration, reconciliation, and API operations.

The pages in this section cover the detailed implementation requirements for each step of the sync process.

<TagsSyncDirectionDiagram />

For a platform-level overview of Tags Sync, including system guarantees and responsibility model, see [Platform Capabilities: Tags Sync](/docs/current/platform/accounting-integrations/imports/tags/tags-sync-overview).

## Tags Sync Execution Model

Tags Sync is a deterministic reconciliation process executed by the integration.

On each sync run, the integration:

1. retrieves selected Dimensions and Dimension Values from the Accounting System
2. retrieves the current state of Tag Groups and Tags from Pleo
3. reconciles Pleo to match the Accounting System state
4. applies the required create, update, unarchive, and archive operations via the Pleo API

<RememberCallout title="Remember">
  The goal of each sync run is to make Pleo reflect the current state of the selected Accounting Dimensions and Dimension Values.
</RememberCallout>

Each sync run must be independent, repeatable, and produce a consistent end state.

## High-Level Process

<IntegrationDesignTagsOverviewDiagram />

## Sync Steps

Tags Sync runs in three steps. Step 1 runs once on first connection to configure which Dimensions to synchronise. Steps 2 and 3 run on a recurring schedule to keep Pleo aligned with the Accounting System.

### Step 1: Select Dimensions

The integration retrieves active Dimensions from the Accounting System and selects which ones to synchronise. On first connection, Dimensions whose code matches an existing active Tag Group in Pleo are automatically pre-selected. The selection is stored in the integration's configuration and used as input to every subsequent sync cycle.

Up to 5 Dimensions may be selected at any time. If a selected Dimension becomes inactive in the Accounting System, it is automatically deselected and its corresponding Tag Group is archived in Pleo.

For the full selection rules, auto-selection logic, and deselection behaviour, see [Dimension Selection](/docs/current/integration-design/accounting-integrations/imports/tags/integration-design-tags-dimension-selection).

### Step 2: Sync Tag Groups with Dimensions

The integration reconciles selected Accounting Dimensions with Tag Groups in Pleo.

#### Outcomes

| Condition                          | Result                       |
| ---------------------------------- | ---------------------------- |
| Matching active Tag Group exists   | Preserve existing Tag Group  |
| Matching archived Tag Group exists | Unarchive existing Tag Group |
| No matching Tag Group exists       | Create new Tag Group         |

After all selected Dimensions are processed, any remaining active Tag Groups that no longer have a matching selected Dimension are archived.

### Step 3: Sync Tags with Dimension Values

For each synchronised Dimension–Tag Group pair, the integration reconciles Dimension Values with Tags.

#### Outcomes

| Condition                    | Result                                    |
| ---------------------------- | ----------------------------------------- |
| Matching active Tag exists   | Preserve Tag and update name if required  |
| Matching archived Tag exists | Unarchive Tag and update name if required |
| No matching Tag exists       | Create new Tag                            |

#### Duplicate Handling

If multiple Tags share the same code:

* retain a single Tag
* archive duplicate Tags
* ensure the retained Tag has the correct current name

After all Dimension Values are processed, any remaining active Tags that no longer have a matching Dimension Value are archived.

## Matching Model

Tag Groups and Tags are each matched to their AS counterparts using the `code` field. For full matching rules, see [Sync Tag Groups with Dimensions](/docs/current/integration-design/accounting-integrations/imports/tags/integration-design-tags-sync-tag-groups#matching-rules) and [Sync Tags with Dimension Values](/docs/current/integration-design/accounting-integrations/imports/tags/integration-design-tags-sync-tags#matching-rules).

## Execution Requirements

The integration is responsible for all sync scheduling and execution behaviour.

| Requirement               | Description                                                                                                                                                                                                                                               |
| ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Scheduling Ownership      | The integration defines sync timing and execution frequency                                                                                                                                                                                               |
| Full Reconciliation       | Every sync execution reconciles against full Accounting System state                                                                                                                                                                                      |
| Non-Overlapping Execution | Sync executions must not overlap                                                                                                                                                                                                                          |
| API Ownership             | All changes are applied through the [Pleo Tags API](/reference/tags-overview). See the [how-to articles](/docs/current/how-tos/accounting-integrations/imports/tags/how-to-select-dimensions-for-tags-sync) for step-by-step implementation instructions. |
| Rate Limit Handling       | Scheduling must respect Accounting System API rate limits. See [Pleo API rate limits](/docs/current/authentication/api-base-urls#rate-limits).                                                                                                            |

For schedule, frequency, and rate limit details, see [Tags Sync Periodicity and Scheduling](/docs/current/integration-design/accounting-integrations/imports/tags/integration-design-tags-periodicity).

## Processing Principles

All implementations must follow these architectural principles.

| Principle                      | Description                                                                |
| ------------------------------ | -------------------------------------------------------------------------- |
| Unidirectional Sync            | Data only flows from the Accounting System into Pleo                       |
| Idempotent Execution           | Re-running the same sync with unchanged data produces the same final state |
| Deterministic Reconciliation   | Identical inputs must produce identical outputs                            |
| Non-Destructive Updates        | Entities are archived instead of deleted                                   |
| Consistent Identity Resolution | Matching logic must behave consistently across executions                  |
| Stateless Execution            | Each sync run must independently reconcile against current source state    |

## Expected Outcome

After implementation:

* Pleo accurately reflects selected Accounting Dimensions
* Tag Groups and Tags remain stable across repeated sync runs
* outdated entities are archived automatically
* duplicate entities are eliminated through reconciliation
* bookkeepers always work with current Tags aligned to the Accounting System

***

## What Comes Next?

* [Dimension Selection](/docs/current/integration-design/accounting-integrations/imports/tags/integration-design-tags-dimension-selection)
* [Sync Tag Groups with Dimensions](/docs/current/integration-design/accounting-integrations/imports/tags/integration-design-tags-sync-tag-groups)
* [Sync Tags with Dimension Values](/docs/current/integration-design/accounting-integrations/imports/tags/integration-design-tags-sync-tags)
* [Data Mapping](/docs/current/integration-design/accounting-integrations/imports/tags/integration-design-tags-data-mapping)
* [Sync Periodicity and Scheduling](/docs/current/integration-design/accounting-integrations/imports/tags/integration-design-tags-periodicity)

Each section describes the detailed implementation requirements for that stage of the sync process.

***

## Related Reading

* [Platform Capabilities: Tags Sync Overview](/docs/current/platform/accounting-integrations/imports/tags/tags-sync-overview)
* [Tags Sync Workflow Guide](/docs/current/guides/accounting-integrations/imports/tags-sync-workflow-guide)
* [Connection and Authorisation Overview](/docs/current/integration-design/auth/integration-design-auth-overview)

***