Skip to main content
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:

​
Data Mapping for Vendor Creation

The DRAFT vendor in Pleo already contains everything needed to create the record in the AS. 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

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

​
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 runs, matched by externalId

​
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). Once Step 1 and Step 2 complete, the vendor’s externalId is populated, and a later export of that same item can succeed.

​
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 to ensure newly activated vendors stay up to date over time.