Skip to main content

​
What You’ll Have Built

After implementing this workflow:
  • New vendors added directly in Pleo are detected reliably, ideally the moment they are created.
  • Each new vendor is created in the Accounting System without manual data entry.
  • The corresponding Pleo Vendor is activated as soon as creation succeeds, using the identifiers assigned by the AS.
  • The integration aligns with Pleo’s Vendor Creation guarantees.

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

​
Vendor Creation Workflow Overview

Vendor Sync assumes a vendor already exists in the AS. But bookkeepers sometimes need to tag an expense to a vendor that doesn’t exist anywhere yet. When that happens, they add it directly in Pleo, and Pleo creates it in DRAFT state, since it has no code or externalId until the AS creates the matching record. Vendor Creation is the integration’s job of turning that DRAFT vendor into a real record in the AS, then confirming back to Pleo that it’s ready to use. Unlike the expense Export workflow, there is no job or batch here. Each new vendor is a single, independent event, detected and processed on its own. The how-to articles in this section use a consistent example to illustrate each step: a bookkeeper adds “Greenfield Logistics” as a new vendor in Pleo.

​
Steps

​
1. Create Vendor in Pleo

​
Purpose

This step is the trigger event for the rest of Vendor Creation: a bookkeeper adds a new vendor directly in Pleo, one that doesn’t exist in the Accounting System yet.

​
Input

  • The vendor’s name, country, and currency, entered by the bookkeeper
  • Optionally, a tax number and registration number

​
Workflow Process

​
Output

  • A new Vendor exists in Pleo with state: DRAFT
  • The Vendor has no code or externalId yet
  • A v1.vendor.created webhook event is emitted

​
Why It Matters

Until a bookkeeper takes this action, there is no DRAFT vendor for your integration to detect. This is a product action, not something your integration builds, but the rest of this workflow only runs in response to it.

​
Step-by-Step Instructions

​
2. Detect Draft Vendor

​
Purpose

This step runs whenever a bookkeeper adds a new vendor in Pleo that has no matching record in the AS yet. The integration must detect this DRAFT vendor before it can create the corresponding record in the AS.

​
Input

  • A vendor created in Pleo with state: DRAFT
  • A v1.vendor.created webhook notification (preferred), or a scheduled polling trigger on a controlled interval of every 5 minutes if webhooks are not used (see Detect Draft Vendors for the full polling contract, including the shared 600 requests/minute budget with Vendor Sync)

​
Workflow Process

​
Output

  • A DRAFT vendor identified and ready for creation in the AS, with its name, country, defaultCurrency, registrationNumber, and taxRegistrationNumber available

​
Why It Matters

Until this vendor is detected, it cannot be created in the AS, and the bookkeeper cannot use it for bookkeeping. Detecting it via webhook, rather than waiting for the next scheduled poll, gets the vendor usable as quickly as possible.

​
Integration Design

If you’re an integration developer or architect, read the Detect Draft Vendors integration design doc before implementing this step. It covers the detection mechanisms (webhook and polling) and why detection must not modify vendor state.

​
Step-by-Step Instructions

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

​
3. Create Vendor in AS

​
Purpose

Using the details from the detected DRAFT vendor, the integration creates the corresponding vendor record in the Accounting System.

​
Input

  • The DRAFT vendor’s name, country, defaultCurrency, registrationNumber, and taxRegistrationNumber
  • A valid connection to the Accounting System

​
Workflow Process

​
Output

  • A new vendor record created in the AS
  • An AS-assigned identifier for the new record, to be used as the Pleo externalId
  • Optionally, an AS-assigned account code, to be used as the Pleo code

​
Why It Matters

This is the step where the vendor becomes real: a record that the Accounting System, and eventually the bookkeeper, can rely on for accounting purposes.

​
Integration Design

If you’re an integration developer or architect, read the Create and Activate Vendors integration design doc before implementing this step. It covers the data mapping, and how to handle a failed creation attempt.

​
Step-by-Step Instructions

​
4. Activate Vendor in Pleo

​
Purpose

Once the vendor exists in the AS, the integration reports its identifiers back to Pleo, transitioning the Vendor from DRAFT to ACTIVE.

​
Input

  • The externalId assigned by the AS (required)
  • The code assigned by the AS, if available (optional)

​
Workflow Process

​
Output

  • The Pleo Vendor’s state transitions to ACTIVE
  • The vendor becomes available for bookkeepers to tag on expenses and invoices, provided Vendor Tagging is enabled for the company. See How to Enable Vendor-Based Bookkeeping
  • The vendor becomes eligible to be matched by future Vendor Sync runs

​
Why It Matters

Without activation, the vendor stays stuck in DRAFT in Pleo even though it now exists in the AS. A bookkeeper can still tag an expense with a DRAFT vendor and export it, but the integration must reject that export item with failureReasonType: vendor_unknown (see How to Update Export Items) until the vendor is activated. Activation is the signal that closes the loop and lets that export succeed.

​
Integration Design

If you’re an integration developer or architect, read the Create and Activate Vendors integration design doc before implementing this step. It covers the activation request, and how it connects back into Vendor Sync.

​
Step-by-Step Instructions

​
Observability and Recovery

Build in enough visibility to detect and recover from failures without manual database inspection:
  • Correlation ID: carry a single identifier for each vendor’s DRAFT-to-ACTIVE lifecycle, from detection through creation and activation, so all log lines for one vendor’s journey can be traced together.
  • Stuck-DRAFT alerting: alert if a DRAFT vendor remains unactivated beyond a defined threshold (for example, several detection cycles or a fixed time window). This usually indicates a failed AS creation call, a permissions issue, or a stuck retry, and won’t otherwise surface until a bookkeeper notices the vendor is unusable.
  • Audit trail: for each vendor, log the detection event, the AS creation attempt (success or failure), and the activation call, so the full DRAFT-to-ACTIVE history can be reconstructed later.

​
What Comes Next?

Once Vendor Creation is live, bookkeepers can add new vendors in Pleo at any time and use them for bookkeeping as soon as the integration activates them. To complete Level 4, also implement the complementary direction: