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

export const VendorCreationLifecycleDiagram = () => {
  const [isDark, setIsDark] = useState(false);
  useEffect(() => {
    const check = () => setIsDark(document.documentElement.classList.contains("dark"));
    check();
    const observer = new MutationObserver(check);
    observer.observe(document.documentElement, {
      attributes: true,
      attributeFilter: ["class"]
    });
    return () => observer.disconnect();
  }, []);
  const nodeFill = isDark ? "#212222" : "#EEF4F4";
  const nodeStroke = isDark ? "#848989" : "#212222";
  const nodeTextStyle = isDark ? ",color:#EEF4F4" : ",color:#131414";
  const linkStyle = isDark ? "" : "linkStyle default stroke:#848989,stroke-width:1px;";
  const themeVariables = {
    fontSize: "12px",
    ...isDark ? {} : {
      edgeLabelBackground: "#FAFCFC"
    }
  };
  const diagram = `
%%{init: {"themeVariables": ${JSON.stringify(themeVariables)}}}%%
flowchart LR
    A[2.Detect Draft Vendor]
    B[3.Create Vendor in AS]
    C[4.Activate Vendor in Pleo]

    A --> B --> C

   style A white-space:normal,fill:${nodeFill},stroke:${nodeStroke}${nodeTextStyle}
   style B white-space:normal,fill:${nodeFill},stroke:${nodeStroke}${nodeTextStyle}
   style C white-space:normal,fill:${nodeFill},stroke:${nodeStroke}${nodeTextStyle}

   click A "/docs/current/integration-design/exports/vendors/integration-design-vendor-creation-detect-draft-vendors"
   click B "/docs/current/integration-design/exports/vendors/integration-design-vendor-creation-create-and-activate"
   click C "/docs/current/integration-design/exports/vendors/integration-design-vendor-creation-create-and-activate"
${linkStyle}
`;
  return <Mermaid chart={diagram} />;
};

export const RememberCallout = ({title, children}) => <div className="callout-box callout-remember">
    <div className="callout-row">
      <span className="callout-icon">
        <svg width="22" height="22" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 256 256" fill="currentColor"><path d="M229.66,98.34,172.39,155.8c11.46,22.93-1.72,45.86-10.11,57a8,8,0,0,1-12,.83L42.34,105.76A8,8,0,0,1,43,93.85c29.65-23.92,57.4-10,57.4-10l57.27-57.46a8,8,0,0,1,11.31,0L229.66,87A8,8,0,0,1,229.66,98.34Z" opacity="0.2" /><path d="M235.32,81.37,174.63,20.69a16,16,0,0,0-22.63,0L98.37,74.49c-10.66-3.34-35-7.37-60.4,13.14a16,16,0,0,0-1.29,23.78L85,159.71,42.34,202.34a8,8,0,0,0,11.32,11.32L96.29,171l48.29,48.29A16,16,0,0,0,155.9,224c.38,0,.75,0,1.13,0a15.93,15.93,0,0,0,11.64-6.33c19.64-26.1,17.75-47.32,13.19-60L235.33,104A16,16,0,0,0,235.32,81.37ZM224,92.69h0l-57.27,57.46a8,8,0,0,0-1.49,9.22c9.46,18.93-1.8,38.59-9.34,48.62L48,100.08c12.08-9.74,23.64-12.31,32.48-12.31A40.13,40.13,0,0,1,96.81,91a8,8,0,0,0,9.25-1.51L163.32,32,224,92.68Z" /></svg>
      </span>
      <div>
        {title && <div className="callout-title">
            {title}
          </div>}
        <div className="callout-body">
          {children}
        </div>
      </div>
    </div>
  </div>;

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.

<RememberCallout title="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).
</RememberCallout>

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:

<VendorCreationLifecycleDiagram />

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)

***