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

# Vendor Sync Implementation Overview

> The architecture and execution model behind Vendor Sync, before implementing the fetch, match, and reconciliation steps.

export const IntegrationDesignVendorSyncOverviewDiagram = () => {
  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 LR
    subgraph Cycle["Recurring Sync Cycle"]
        B[Sync Triggered]
        C[Fetch Active Vendors from AS]
        D[Fetch Active and Archived Vendors from Pleo]

        subgraph Step["Reconcile Vendors"]
            E[Match by externalId]
            F[Create / Unarchive / Update / Preserve]
            G[Archive Unmatched]
            E --> F --> G
        end

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

    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 K white-space:normal,fill:${nodeFill},stroke:${nodeStroke}${nodeTextStyle}
    style Cycle fill:${subgraphFill},stroke:${subgraphStroke}${subgraphTextStyle}
    style Step fill:${subgraphFill},stroke:${subgraphStroke}${subgraphTextStyle}
${linkStyle}
`;
  return <Mermaid chart={diagram} />;
};

export const VendorSyncDirectionDiagram = () => {
  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["Vendors"]
end

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

subgraph Pleo["Pleo"]
    target["Vendors"]
end

AS -.-> Integration
Integration -->|"Pleo Vendors API"| Pleo

style source white-space:normal,fill:${outerFill},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 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 Vendor Sync between an Accounting System and Pleo.

It maps vendor records from the Accounting System to the equivalent Vendors 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 the sync process.

<VendorSyncDirectionDiagram />

Vendor Sync ensures Pleo always has a current, accurate list of vendors. Stale or missing vendors prevent bookkeepers from tagging expenses and invoices to the correct vendor.

<RememberCallout title="Remember">
  This section covers the Accounting System → Pleo direction only. For the complementary Pleo → Accounting System direction, where a bookkeeper creates a new vendor directly in Pleo, see [Integration Design: Vendor Creation Overview](/docs/current/integration-design/exports/vendors/integration-design-vendor-creation-overview).
</RememberCallout>

For the full vendor-to-bookkeeping chain, see [Platform Capabilities: Vendor Sync](/docs/current/platform/accounting-integrations/imports/vendors/vendor-sync-overview).

## Vendor Sync Execution Model

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

On each sync run, the integration:

1. Retrieves active vendors from the Accounting System
2. Retrieves the current state of Vendors from Pleo (active and archived)
3. Reconciles Pleo to match the Accounting System state
4. Applies the required create, update, unarchive, and archive operations via the Pleo Vendors API

<RememberCallout title="Remember">
  The goal of each sync run is to make Pleo reflect the current active vendors from the Accounting System.
</RememberCallout>

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

## High-Level Process

<IntegrationDesignVendorSyncOverviewDiagram />

## Matching Model

Vendors are matched to their AS counterparts using the `externalId` field. For full matching rules, see [Sync Vendors](/docs/current/integration-design/accounting-integrations/imports/vendors/integration-design-vendor-sync).

## Sync Process

Vendor Sync runs as a single reconciliation step on every sync cycle.

The integration fetches active vendors from the Accounting System and all Vendors (active and archived) from Pleo, then reconciles the two using the `externalId` field.

### Reconciliation Outcomes

| Condition                                      | Result                                                                                                                               |
| ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| Matching active Vendor in Pleo, details match  | Preserve existing Vendor                                                                                                             |
| Matching active Vendor in Pleo, details differ | Update Vendor's `code`, `country`, `defaultCurrency`, `name`, `registrationNumber`, and `taxRegistrationNumber` to match AS          |
| Matching archived Vendor in Pleo               | Unarchive Vendor and update details if needed                                                                                        |
| No matching Vendor in Pleo                     | Create new Vendor with `externalId`, `code`, `country`, `defaultCurrency`, `name`, `registrationNumber`, and `taxRegistrationNumber` |

After all Accounting System vendors are processed, any remaining active Vendors in Pleo that had no match are archived, once that Vendor has been unmatched for at least two consecutive sync runs (a single run's transient omission is not enough; see [Sync Vendors](/docs/current/integration-design/accounting-integrations/imports/vendors/integration-design-vendor-sync#4-archive-unmatched-vendors) for the full rule).

For the full reconciliation algorithm and step-by-step implementation instructions, see [Sync Vendors](/docs/current/integration-design/accounting-integrations/imports/vendors/integration-design-vendor-sync).

## Execution Requirements

| 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. See [collision handling](/docs/current/integration-design/accounting-integrations/imports/vendors/integration-design-vendor-sync-periodicity#ad-hoc-vendor-sync) for what to do if a trigger arrives while a run is already in progress. |
| API Ownership             | All changes are applied through the [Pleo Vendors API](/reference/vendor/vendors-api-overview). See the [how-to article](/docs/current/how-tos/accounting-integrations/imports/vendors/how-to-fetch-and-match-vendors) for step-by-step implementation instructions.       |
| Rate Limit Handling       | Scheduling must respect the [Pleo Vendors API rate limit](/docs/current/integration-design/accounting-integrations/imports/vendors/integration-design-vendor-sync-periodicity#pleo-api-rate-limit).                                                                        |

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

## Processing Principles

| Principle                      | Description                                                                |
| ------------------------------ | -------------------------------------------------------------------------- |
| Unidirectional Sync            | Data only flows from the Accounting System into Pleo for this process      |
| 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        | Vendors 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 the active vendors from the Accounting System
* Vendors remain stable across repeated sync runs
* Outdated vendors are archived automatically
* Bookkeepers always have current, accurate vendors available for tagging expenses and invoices

***

## What Comes Next?

* [Sync Vendors](/docs/current/integration-design/accounting-integrations/imports/vendors/integration-design-vendor-sync)
* [Vendor Sync Data Mapping](/docs/current/integration-design/accounting-integrations/imports/vendors/integration-design-vendor-sync-data-mapping)
* [Vendor Sync Periodicity and Scheduling](/docs/current/integration-design/accounting-integrations/imports/vendors/integration-design-vendor-sync-periodicity)

***

## Related Reading

* [Platform Capabilities: Vendor Sync Overview](/docs/current/platform/accounting-integrations/imports/vendors/vendor-sync-overview)
* [Vendor Sync Workflow Guide](/docs/current/guides/accounting-integrations/imports/vendor-sync-workflow-guide)
* [Integration Design: Vendor Creation Overview](/docs/current/integration-design/exports/vendors/integration-design-vendor-creation-overview)
* [Connection and Authorisation Overview](/docs/current/integration-design/auth/integration-design-auth-overview)

***