Skip to main content
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.

​
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
Each sync run must be independent, repeatable, and produce a consistent end state.

​
High-Level Process

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

​
Step 2: Sync Tag Groups with Dimensions

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

​
Outcomes

ConditionResult
Matching active Tag Group existsPreserve existing Tag Group
Matching archived Tag Group existsUnarchive existing Tag Group
No matching Tag Group existsCreate 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

ConditionResult
Matching active Tag existsPreserve Tag and update name if required
Matching archived Tag existsUnarchive Tag and update name if required
No matching Tag existsCreate 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

All reconciliation logic follows these rules:
RuleDescription
Code-Based IdentityMatching is performed using codes, never names
Case-Insensitive MatchingCodes must be compared case-insensitively
Mutable NamesNames may change over time and must not be treated as stable identifiers
Stable IdentityCodes represent long-term entity identity across sync runs
This model ensures consistent reconciliation behaviour across repeated executions.

​
Scheduling and Execution

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

​
Execution Requirements

RequirementDescription
Scheduling OwnershipThe integration defines sync timing and execution frequency
Full ReconciliationEvery sync execution reconciles against full Accounting System state
Non-Overlapping ExecutionSync executions must not overlap
API OwnershipAll changes are applied through the Pleo Tags API. See the how-to articles for step-by-step implementation instructions.
Rate Limit HandlingScheduling must respect Accounting System API rate limits. See Pleo API rate limits.

​
Scheduled Execution

Most integrations execute Tags Sync periodically (commonly every 60 minutes). Each scheduled run:
  1. retrieves Accounting System state
  2. reconciles Pleo against that state
  3. applies all required updates via the API

​
Manual Execution (Optional)

Integrations may optionally support manual sync triggers. Manual execution must follow the same reconciliation rules and execution model as scheduled runs.

​
Processing Principles

All implementations must follow these architectural principles.
PrincipleDescription
Unidirectional SyncData only flows from the Accounting System into Pleo
Idempotent ExecutionRe-running the same sync with unchanged data produces the same final state
Deterministic ReconciliationIdentical inputs must produce identical outputs
Non-Destructive UpdatesEntities are archived instead of deleted
Consistent Identity ResolutionMatching logic must behave consistently across executions
Stateless ExecutionEach 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?

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