> ## Documentation Index
> Fetch the complete documentation index at: https://developers.pleo.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Vendor Creation Overview

> The architecture and execution model behind Vendor Creation, before implementing detection, creation, and activation.

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.

Remember

This section covers the Pleo → Accounting System direction only. For the complementary Accounting System → Pleo direction, where existing vendors are kept in sync, see [Integration Design: Vendor Sync Implementation Overview](/docs/current/integration-design/accounting-integrations/imports/vendors/integration-design-vendor-sync-overview).

For the conceptual overview, see [Platform Capabilities: Vendor Creation](/docs/current/platform/exports/vendors/vendor-creation-overview).

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

| Pleo Responsibilities | Integration Responsibilities |
| - | - |
| Let the bookkeeper enter vendor details in the Web App | Detect new `DRAFT` vendors, via webhook or scheduled polling |
| Store the vendor in `DRAFT` state | Create the corresponding record in the Accounting System |
| Emit the `v1.vendor.created` webhook event | Report the `code` and `externalId` back to Pleo via `POST :activate` |
| Transition the vendor to `ACTIVE` on activation | Handle retries safely without creating duplicate AS records |

## 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](/docs/current/integration-design/exports/vendors/integration-design-vendor-creation-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](/docs/current/integration-design/exports/vendors/integration-design-vendor-creation-detect-draft-vendors)

***

## Related Reading

* [Vendor Creation Workflow Guide](/docs/current/guides/vendor-creation-workflow-guide)
* [Platform Capabilities: Vendor Creation](/docs/current/platform/exports/vendors/vendor-creation-overview)
* [Integration Design: Vendor Sync Implementation Overview](/docs/current/integration-design/accounting-integrations/imports/vendors/integration-design-vendor-sync-overview)

***