Vendor Creation Overview

Vendor Creation lets a bookkeeper add a new vendor directly in Pleo, even if it doesn’t exist in the Accounting System yet. The integration then creates the vendor in the Accounting System automatically. This is the reverse of Vendor Sync, which keeps Pleo up to date with vendors that already exist in the Accounting System.

Purpose of Vendor Creation

Vendor Creation exists to:

Let a bookkeeper add a new vendor directly in Pleo, without first creating it in the Accounting System
Create that vendor reliably in the Accounting System, without manual data entry
Let the bookkeeper use the vendor right away, instead of waiting for the next scheduled Vendor Sync
Keep the vendor’s identifiers (code, externalId) consistent across both systems once creation completes. The :activate call does not sync back descriptive fields, like name, country, currency, and tax and registration numbers. The Vendor Sync workflow picks those up later

What Is a Draft Vendor?

A bookkeeper can add a vendor in Pleo before it exists in the Accounting System. Pleo then creates the record in DRAFT state.

Vendor State	Meaning
`DRAFT`	The vendor exists in Pleo only. It still needs to be created in the Accounting System.
`ACTIVE`	The vendor exists in both Pleo and the Accounting System. It carries an `externalId`, and a `code` if the Accounting System assigns one. It can be used for bookkeeping.
`ARCHIVED`	The vendor is no longer active in the Accounting System.

A DRAFT vendor has no code or externalId yet. The Accounting System assigns both once it creates the record.

Core Concept

The full chain is:

Bookkeeper adds a vendor in Pleo: the vendor is created in DRAFT state
Pleo notifies the integration: a v1.vendor.created webhook event is sent, or the integration detects the new DRAFT vendor via scheduled polling
Integration creates the vendor in the Accounting System: using the details from the DRAFT vendor
Integration activates the vendor in Pleo: passing back the code and externalId assigned by the Accounting System

System Guarantees

Guarantee	Description
Source of Truth	Pleo is the source of truth for a vendor’s initial details (name, country, currency, tax and registration numbers)
Single Direction per Event	Each Vendor Creation event flows from Pleo into the Accounting System
Identity Assignment	The Accounting System always assigns `code` and `externalId`, never Pleo
Non-Destructive Behaviour	A `DRAFT` vendor is never deleted while it waits to be created. It stays visible until activated
Idempotency	Re-processing the same `v1.vendor.created` event must not create duplicate vendors in the Accounting System

Responsibility Model

Pleo Responsibilities

Area	Responsibility
Vendor Capture	Let the bookkeeper enter the new vendor’s details in the Web App
Draft Storage	Store the vendor in `DRAFT` state until activated
Notification	Emit the `v1.vendor.created` webhook event when a `DRAFT` vendor is created

Integrator Responsibilities

Area	Responsibility
Detection	Detect new `DRAFT` vendors, via webhook or scheduled polling
Creation	Create the corresponding vendor record in the Accounting System
Activation	Report the `code` and `externalId` back to Pleo so the vendor becomes `ACTIVE`

Operational Model

Creation Direction

Vendor Creation flows in the opposite direction to Vendor Sync:

Pleo is the source of truth for the vendor’s initial details
The integration creates the corresponding record in the Accounting System
The Accounting System is the source of truth for the resulting code. The integration reports that code back to Pleo

Operational Constraints

Constraint	Description
Detection Ownership	The integration is responsible for detecting new `DRAFT` vendors, ideally via webhook
Single-Item Processing	Each `DRAFT` vendor is processed independently as its own event
Rate Limits	The integration must respect two rate limits. The first is the target Accounting System’s own API rate limit; it varies by AS, and it’s the integration’s own responsibility to determine it. The second is Pleo’s Vendors API rate limit. Pleo’s limit is 600 requests/minute per credential, shared across Vendor Creation’s draft-vendor polling and vendor activation and Vendor Sync’s scheduled and ad hoc runs. Size this workflow’s request volume against that combined budget, not in isolation. See Backpressure and Throttling for what to do on a `429`.
Required Scopes	The integration’s credential must include the Vendors API scopes needed to read `DRAFT` vendors and activate them (see Vendors API Scopes). If you use webhook detection, the credential also needs webhook subscription permissions. A missing scope causes the specific request to fail with `403`, not `401`; that’s distinct from the expired or revoked credential case below. Request the required scope during OAuth client registration or when creating an API Key.
Credential Failures	If Vendor Creation hits a `401` or `403` because of an expired, revoked, or rotated credential, stop processing. Don’t continue with partial or unauthenticated calls. Resume once the credentials are restored. See How to Handle Token Expiry or Revocation.
Forward Compatibility	Vendors API responses may gain new draft-vendor fields, new `state` values, and extra pagination metadata over time. Build the integration to ignore fields and values it doesn’t recognise, instead of failing on them. Treat this suite’s documented field list, and the `DRAFT`/`ACTIVE` states covered above, as the current set, not a permanent one. Vendor Sync separately handles the `ARCHIVED` state.
Concurrency / Locking	Vendor Creation shares a per-company concurrency lock with Vendor Sync. This stops the two workflows from writing to the same company’s vendors at the same time. Hold the lock for the full lifetime of a pending activation (from AS creation succeeding to activation succeeding), not just for the Step 1/Step 2 calls. Otherwise, Vendor Sync could later create a duplicate for an AS vendor that is still `DRAFT` in Pleo. See Create and Activate: Failure Handling for the full detail.

For webhook and polling schedule details, see Vendor Creation Workflow Guide. It includes the recommended 5-minute polling interval for when you don’t use webhooks.

Get Started

Authentication and Authorisation

Platform Capabilities & Concepts

Integration Design

Workflow Guides

How-to's

GLOSSARY

ARCHIVED

Vendor Creation Overview

Purpose of Vendor Creation

What Is a Draft Vendor?

Core Concept

System Guarantees

Responsibility Model

Pleo Responsibilities

Integrator Responsibilities

Operational Model

Creation Direction

Operational Constraints

​Purpose of Vendor Creation

​What Is a Draft Vendor?

​Core Concept

​System Guarantees

​Responsibility Model

​Pleo Responsibilities

​Integrator Responsibilities

​Operational Model

​Creation Direction

​Operational Constraints

​Related Reading

Purpose of Vendor Creation

What Is a Draft Vendor?

Core Concept

System Guarantees

Responsibility Model

Pleo Responsibilities

Integrator Responsibilities

Operational Model

Creation Direction

Operational Constraints

Related Reading