Vendor Creation Overview

This section describes how to implement Vendor Creation from Pleo into an Accounting System. It covers what happens when a bookkeeper adds a new vendor directly in Pleo, before that vendor exists anywhere in the Accounting System. For the conceptual overview, see Platform Capabilities: Vendor Creation.

​

Design Guarantees

Pleo provides the following guarantees for the Vendor Creation workflow. Integrations must implement processing logic to fully realise these guarantees.

• Single-Item Processing: Each new vendor is its own independent unit of work; there is no batching or job concept, unlike expense Export Jobs.
• Deterministic Outcome: A DRAFT vendor ends in ACTIVE state once the integration successfully creates it in the AS and reports back its identifiers.
• Non-Destructive Waiting State: A vendor remains visible in Pleo as DRAFT for as long as it takes the integration to create it in the AS; it is never removed while waiting.
• Idempotency: Reprocessing the same v1.vendor.created event must not create duplicate vendor records in the AS.

​

Purpose of Vendor Creation

Vendor Creation lets a bookkeeper add a vendor to Pleo the moment they need it, without first having to create it manually in the Accounting System and waiting for the next Vendor Sync cycle.

​

Vendor Creation Processing Model

​

Draft Vendor

A vendor created directly in Pleo, without an existing AS record, starts in DRAFT state. It has no code or externalId yet.

​

Activation

Once the integration creates the corresponding record in the AS, it reports the AS-assigned code and externalId back to Pleo. This transitions the vendor to ACTIVE state.

​

Vendor Creation Lifecycle

Vendor Creation processing follows a deterministic pipeline: Each step in the diagram above is clickable and links to its corresponding Integration Design section.

​

Responsibility Model

Vendor Creation is a shared responsibility between Pleo and the integration.

​

Processing Principles

All Vendor Creation integrations must follow these principles:

​

Single-Item Processing

Each DRAFT vendor is processed independently; a delay or failure on one vendor does not block others. This independence is about processing throughput, not locking: the per-company concurrency lock shared with Vendor Sync (see Create and Activate: Failure Handling) is company-scoped, so a vendor whose activation is pending can still cause another DRAFT vendor for the same company to wait briefly for that lock. Only one company’s vendors are ever affected by another company’s lock.

​

Deterministic Outcome

Each DRAFT vendor must eventually reach ACTIVE state once successfully created in the AS.

​

Idempotent Design

Integrations should safely retry detection and creation without creating duplicate vendor records in the AS.

​

Expected Outcome

After implementing this workflow, the integration will:

• reliably create, in the Accounting System, every vendor a bookkeeper adds in Pleo
• activate the corresponding Pleo Vendor as soon as creation succeeds
• avoid duplicate vendor records in the Accounting System, even under retries

---

​

What Comes Next?

• Detect Draft Vendors

---

​

Related Reading

• Vendor Creation Workflow Guide
• Platform Capabilities: Vendor Creation
• Integration Design: Vendor Sync Implementation Overview

---