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

# Create and Activate Vendors

> How to create a vendor in the Accounting System from a DRAFT Pleo vendor, then activate it back in Pleo, including failure handling.

This page describes how integrations create a vendor in the Accounting System from a `DRAFT` Pleo vendor, then activate the corresponding Vendor in Pleo.

This covers the **second and third steps** in the Vendor Creation workflow, run immediately after a `DRAFT` vendor is detected.

## Implementation

See the corresponding how-to articles for API usage and step-by-step instructions:

* [How to Create a Vendor in the AS](/docs/current/how-tos/accounting-integrations/vendors/how-to-create-vendor-in-as)
* [How to Activate a Vendor in Pleo](/docs/current/how-tos/accounting-integrations/vendors/how-to-activate-vendor-in-pleo)

## Data Mapping for Vendor Creation

The `DRAFT` vendor in Pleo already contains everything needed to create the record in the AS.

| Pleo Vendor Field | AS Vendor Datapoint |
| - | - |
| `name` | Official name of the vendor |
| `country` | Country of the vendor (ISO 3166-1 alpha-2 country code) |
| `defaultCurrency` | Default currency for the vendor's financial operations (ISO 4217 currency code, 3 letters) |
| `registrationNumber` | The vendor's registration number, if provided |
| `taxRegistrationNumber` | The vendor's VAT / GST / Tax ID number, if provided |

A `DRAFT` vendor has no `code` or `externalId` yet. Both are assigned by the AS once the record is created there.

## Step 1: Create the Vendor in the AS

Using the fields above, create the corresponding vendor record in the Accounting System.

### Output

* A new vendor record in the AS
* An AS-assigned identifier for the new record, used as the Pleo `externalId`
* Optionally, an AS-assigned account code, used as the Pleo `code`

Remember

If the AS has no separate stable identifier beyond the account code, `code` and `externalId` can be the same value.

## Step 2: Activate the Vendor in Pleo

Report the identifiers assigned by the AS back to Pleo so the Vendor transitions from `DRAFT` to `ACTIVE`.

| Pleo Vendors API Field | Requirement |
| - | - |
| `externalId` | Required. The identifier assigned to the new vendor by the AS. |
| `code` | Optional. The account code assigned to the new vendor by the AS, if available. |

### Output

* The Pleo Vendor's `state` transitions to `ACTIVE`
* The Vendor becomes available for bookkeepers to tag on expenses and invoices
* The vendor is now eligible to be picked up by future [Vendor Sync](/docs/current/integration-design/accounting-integrations/imports/vendors/integration-design-vendor-sync-overview) runs, matched by `externalId`

Remember

This create-and-activate step must not run concurrently with [Vendor Sync](/docs/current/integration-design/accounting-integrations/imports/vendors/integration-design-vendor-sync) for the same company. Overlapping execution can cause Sync to create a duplicate Vendor for an AS record still in flight here, or archive a Vendor this flow just activated if Sync's AS fetch has not yet caught up. Use the same per-company concurrency lock for both workflows.

## Failure Handling

Step 1 (AS creation) and Step 2 (activation in Pleo) can each fail independently, and each failure mode needs different handling to avoid duplicate records or a vendor stuck in limbo.

### If AS Creation Fails

If creating the vendor in the AS fails, the integration must not call activate. The vendor remains `DRAFT` in Pleo and should be retried on the next detection cycle.

Retries must not create duplicate vendor records in the AS. If the integration cannot confirm whether a previous attempt already created the record, check for an existing AS vendor with matching details before creating a new one. "Matching details" must be exact, not fuzzy: where the Accounting System supports a custom reference or memo field on vendor records, the integration must store the `DRAFT` vendor's Pleo `id` (and its `companyId`, for integrations serving multiple Pleo companies against the same AS) on the AS vendor record at creation time, and use that stored `id` (and `companyId`) for retry lookups instead of matching on `name`, which can produce false positives or false negatives.

### If Activation Fails

AS creation succeeding is not the same as the vendor being fully created. The vendor is only done once activation in Pleo has also succeeded.

If the `:activate` call fails, times out, or its outcome is unknown (for example, a network error after the request was sent), the integration must not re-run Step 1 and create a second AS record. Instead, persist the AS-assigned `externalId` (and `code`, if returned) durably as soon as Step 1 succeeds, and retry only Step 2, the `:activate` call, using those stored identifiers, on the next detection cycle or a dedicated retry job.

A `DRAFT` vendor whose AS record already exists must be distinguishable, at retry time, from one that still needs AS creation. Storing the AS-assigned identifiers against the Pleo `id` as soon as they exist is what makes that distinction possible.

### Interaction with Vendor Sync

The per-company concurrency lock with Vendor Sync (see Step 2 above) only prevents literally overlapping execution. It does not, by itself, prevent a **later, non-overlapping** Vendor Sync run from creating a duplicate Vendor: if Step 1 succeeds but Step 2 fails or times out, the AS vendor now exists while the Pleo vendor is still `DRAFT` and therefore invisible to Sync's `ACTIVE`/`ARCHIVED` matching. A Sync run any time after that failure, not just a concurrent one, will see that AS vendor as unmatched and create a duplicate Pleo Vendor for it.

To close this gap, either:

* Hold the per-company lock for the full lifetime of a pending activation, not just for the duration of the Step 1/Step 2 calls, releasing it only once activation succeeds or the `DRAFT` vendor is abandoned per your retry-abandonment policy; or
* Have Vendor Sync's matching step cross-check pending-activation AS identifiers (the ones persisted above) before creating, and skip creation for any AS vendor already claimed by an in-flight or retryable Vendor Creation attempt.

### Interaction with Expense Export

A bookkeeper can tag an expense with a `DRAFT` vendor and submit it for export before Step 1 and Step 2 above have completed. Pleo does not block this.

The export item's vendor object has no `state` field, so the integration cannot check for `DRAFT` or `ACTIVE` directly. Check `externalId` instead: an empty `externalId` means the vendor doesn't exist in the AS yet. In that case, reject the export item rather than attempting to post it. Report it back to Pleo with `failureReasonType: vendor_unknown` (see [How to Update Export Items](/docs/current/how-tos/accounting-integrations/how-to-update-export-items-for-as-erp-processing#2-build-update-payload)). Once Step 1 and Step 2 complete, the vendor's `externalId` is populated, and a later export of that same item can succeed.

Remember

Do not create the AS vendor record as a side effect of this export failure. Vendor creation and activation stay driven by Step 1 and Step 2 above, on their own detection cycle, not by an export attempt hitting a `DRAFT` vendor.

## Processing Order

## Upstream Dependencies

* A `DRAFT` vendor detected in Pleo
* A valid connection to the Accounting System

## Downstream Dependencies

* Vendor Tagging and Accounts Payable bookkeeping, once the Vendor is `ACTIVE`
* Future Vendor Sync runs, which will now match this Vendor by `externalId`

***

## What Comes Next?

Once Vendor Creation is implemented, review [Vendor Sync](/docs/current/integration-design/accounting-integrations/imports/vendors/integration-design-vendor-sync-overview) to ensure newly activated vendors stay up to date over time.

***

## Related Reading

* [How to Create a Vendor in the AS](/docs/current/how-tos/accounting-integrations/vendors/how-to-create-vendor-in-as)
* [How to Activate a Vendor in Pleo](/docs/current/how-tos/accounting-integrations/vendors/how-to-activate-vendor-in-pleo)
* [Vendor Creation Workflow Guide](/docs/current/guides/vendor-creation-workflow-guide)
* [Platform Capabilities: Vendor Creation](/docs/current/platform/exports/vendors/vendor-creation-overview)

***