Tags Sync Workflow Guide

​

What You’ll Have Built

After implementing this workflow:

• Accounting Dimensions from the AS are reflected as Tag Groups in Pleo.
• Dimension Values are reflected as Tags within each Tag Group.
• Tags are automatically kept up-to-date on a scheduled basis.
• Bookkeepers can assign current, accurate Dimensions to expenses in Pleo.
• The integration aligns with Pleo’s Tags Sync guarantees and matching model.

​

Who This Guide Is For

This guide is intended for:

• Integration developers
• Solution architects
• Accounting platform integrators

It focuses on workflow understanding, not implementation details.

​

Before You Start

You should be familiar with:

• Pleo’s supported authentication methods.
• The Tags Sync platform capabilities page.

​

Tags Sync Workflow Overview

In the Accounting System, Dimensions represent categories used to classify expenses (such as Department, Cost Centre, or Project). Each Dimension contains Dimension Values, which are the individual options a bookkeeper can assign to an expense (such as Engineering, Marketing, or Operations). Tags Sync maps this structure into Pleo. Dimensions become Tag Groups and Dimension Values become Tags. The Accounting System is the source of truth; the integration’s role is to keep Pleo’s Tag Groups and Tags aligned with the current state of the AS so bookkeepers always have accurate, up-to-date options when coding expenses. Step 1 runs once on first connection and configures which Dimensions to synchronise. Steps 2 and 3 run together on a schedule, keeping Pleo in sync with the AS as Dimensions and Dimension Values change over time. Each step produces outputs required by the next. The how-to articles in this section use a consistent example to illustrate each step. The table below shows the starting state in both systems before the sync process runs. The three steps progress as follows:

---

​

Steps

​

1. Select Dimensions

​

Purpose

Before Tags Sync can run, the integration must know which Accounting Dimensions from the AS to synchronise. This step configures that selection and stores it for every subsequent sync cycle. On first connection, the integration automatically pre-selects Dimensions whose code matches an existing active Tag Group in Pleo. This reduces setup effort for integrators who have previously configured Tags manually in Pleo. Any remaining Dimensions can be selected manually, up to a maximum of 5 in total. On subsequent connections, the stored selection is restored from the integration’s configuration. No re-selection is needed. If a previously selected Dimension has become inactive in the AS since the last sync, it is automatically deselected and its corresponding Tag Group is archived in Pleo.

​

Input

• Active Dimensions from the AS (only active Dimensions are eligible for selection)
• Existing active Tag Groups from Pleo, used to determine which Dimensions can be auto-selected on first connection. If there are no active Tag Groups in Pleo, nothing is auto-selected and all Dimensions must be selected manually.

​

Workflow Process

​

Output

• Dimensions auto-selected where their code matches an active Pleo Tag Group (first connection only)
• Dimensions that have become inactive in the AS automatically removed from the selection
• Up to 5 Dimensions stored in the integration’s configuration, ready for use in every sync cycle

​

Why It Matters

The Dimension selection defines the scope of every sync cycle that follows. Only selected, active Dimensions are synchronised, so the selection must reflect what bookkeepers actually need to code expenses against. Auto-selection eliminates manual setup when reconnecting or reconfiguring after Tags have already been created in Pleo, and automatic deselection of inactive Dimensions keeps the selection clean without requiring manual intervention.

​

Integration Design

If you’re an integration developer or architect, read the Dimension Selection integration design doc before implementing this step. It covers the rules and constraints your implementation must comply with, including selection limits, auto-selection matching logic, how inactive Dimensions are handled, and what deselecting a Dimension does to the corresponding Tag Group in Pleo.

​

Step-by-Step Instructions

When you’re ready to start implementing, follow the step-by-step instructions in the accompanying How-to article.

---

​

2. Sync Tag Groups with Dimensions

​

Purpose

This step runs at the start of every Tags Sync cycle, immediately after the Dimension selection is confirmed. The integration retrieves the selected Dimensions from its configuration, then retrieves all Tag Groups from Pleo, both active and archived, and aligns them. For each selected Dimension, the integration looks for a matching Tag Group in Pleo by code (case-insensitive). If a match is found and the Tag Group is archived, it is unarchived. If no match exists, a new Tag Group is created. If the Tag Group name differs from the AS, it is updated to match. Any active Tag Group in Pleo that no longer has a matching selected Dimension is archived. This covers Dimensions that were deselected or became inactive since the last sync cycle.

​

Input

• Selected active Dimensions from the integration’s configuration (the Dimensions chosen in Step 1 that are still active in the AS)
• Active and archived Tag Groups from Pleo. Archived Tag Groups are included so they can be unarchived rather than duplicated if a Dimension is re-selected.

​

Workflow Process

​

Output

• Tag Groups created for Dimensions with no existing match in Pleo
• Archived Tag Groups unarchived where a selected Dimension matches
• Tag Group names updated where they differ from the current AS Dimension name
• Active Tag Groups archived where their Dimension is no longer selected

​

Why It Matters

Tag Groups are the containers that hold Tags. If this step is not run correctly, the structure bookkeepers rely on to code expenses will be out of date. Tag Group sync ensures the Pleo structure mirrors the AS before any Tags are processed, so Tags always end up in the right place.

​

Integration Design

If you’re an integration developer or architect, read the Sync Tag Groups with Dimensions integration design doc before implementing this step. It covers the matching rules, archiving behaviour, and how the sync handles inactive Dimensions discovered during the cycle.

​

Step-by-Step Instructions

When you’re ready to start implementing, follow the step-by-step instructions in the accompanying How-to article.

---

​

3. Sync Tags with Dimension Values

​

Purpose

This step runs immediately after Tag Group sync, once for every active Tag Group in Pleo. For each Tag Group, the integration retrieves the corresponding Dimension Values from the AS and the current Tags from Pleo, then aligns them. Tags are matched to Dimension Values by code (case-insensitive). Matched Tags that are archived are unarchived. Tags whose names differ from the AS are updated. If a Dimension Value has no matching Tag, a new Tag is created. Active Tags with no matching Dimension Value are archived. The step also handles duplicate Tags (where multiple Tags in Pleo share the same code) by retaining the best match and archiving the rest.

​

Input

• Active Dimension Values from the AS for each selected Dimension (only active values are processed; inactive, blocked, or expired values result in the corresponding Tag being archived)
• Active and archived Tags from Pleo for each Tag Group. Archived Tags are included so they can be unarchived if the corresponding Dimension Value becomes active again.

​

Workflow Process

​

Output

• Tags created for Dimension Values with no existing match in Pleo
• Archived Tags unarchived where a Dimension Value matches
• Tag names updated where they differ from the current AS Dimension Value name
• Active Tags archived where their Dimension Value is no longer active in the AS
• Duplicate Tags resolved by retaining the best match and archiving the rest

​

Why It Matters

Tags are what bookkeepers see and use when coding expenses. If Tags are out of date, bookkeepers may assign incorrect Dimensions, leading to errors when expenses are exported to the AS. This step ensures every active Dimension Value in the AS is available as a Tag in Pleo, and that stale Tags are removed before they cause problems.

​

Integration Design

If you’re an integration developer or architect, read the Sync Tags with Dimension Values integration design doc before implementing this step. It covers matching rules, duplicate resolution logic, the conditions under which Tags are archived, and how the sync handles edge cases like expired or blocked Dimension Values.

​

Step-by-Step Instructions

When you’re ready to start implementing, follow the step-by-step instructions in the accompanying How-to article.

---

​

What Comes Next?

After implementing Tags Sync, you can extend your integration with:

• Accounts Sync
• Tax Sync

---

​

Related Reading

• Integration Design - Tags Sync Overview
• Platform Capabilities — Tags Sync

---