Managing B2B prospects

This feature is only available for stores using B2B Buyer Portal, which is currently available to selected accounts.

A prospect is a buyer organization that has registered but is not yet cleared to buy. It is a contract held inactive while its review runs.

B2B Buyer Portal stores the prospect contract, address, and storefront user profile in Master Data v1, as documents in the CL, AD, and shopper entities. For how these records relate, see B2B Buyer Portal Master Data architecture and Master Data.

Prospect registration is integrator-driven. VTEX exposes no prospect-registration endpoint, so you assemble the prospect yourself by calling core platform APIs directly. Use the B2B Contracts API for the CL contract document, the B2B Addresses API for the AD address, and the Organization Units API for the unit that scopes the contract. The storefront user comes from Authenticator, License Manager, and the shopper entity, the Master Data entity that holds the storefront user's profile data.

A prospect is a CL document carrying three values:

• prospectWorkflow set to PENDING
• approved set to false
• isActive set to false

Everything else on the document is a normal contract.

If you omit prospectWorkflow when you create the CL document, the field stays null and the record is an ordinary contract, not a prospect. It will not be returned when you search for prospects by state.

This guide covers what must exist for a prospect to be reviewable, how to confirm it, and how to move the prospect between review states.

• The store must have B2B Buyer Portal enabled.
• Requests must be authenticated with an App Key and App Token pair or with a valid VtexIdclientAutCookie header. Learn more about API authentication.
• The user or API key must hold the License Manager resources listed in the Permissions section of each endpoint you call. Writing CL and AD documents requires Dynamic Storage resources, the License Manager resource family that covers Master Data document operations. Reading organization units requires Organization Units resources.

A prospect starts as a CL document. Three fields define it as a prospect rather than as an ordinary contract:

The response returns documentId, which is the contract ID. The remaining steps use it.

For the complete field list and the field descriptions, see POST Create contract.

The contract alone is not reviewable. A prospect is a set of related records spread across several platform APIs, and the following table lists only what the prospect flow requires of each piece. For the entity-relationship context, the full field inventory, and the linking fields between these entities, see B2B Buyer Portal Master Data architecture.

The storefront user is what lets the buyer sign in to their Organization Account. It is not part of the eligibility conditions, so a prospect can be reviewed before it has one.

To list prospects, you can use the Master Data search operation on the CL data entity and filter by prospectWorkflow. Values in _where are uppercase.

To list the contracts that never went through prospect review, filter by _where=prospectWorkflow is null.

The REST-Range header is required, and a single query returns at most 100 documents. For the query syntax, pagination headers, and response shape, see GET Search documents.

Two conditions must hold before you approve a prospect, and both are yours to check. Run them against the contract ID returned in Step 1.

First, confirm that an organization unit's contractIds scope contains the contract ID. The request must return at least one unit. A 204 No Content or a 404 Not Found response means no unit references the contract.

Second, confirm that at least one active address references the contract ID in userId.

For the full operation details, see GET Find all organization units with scope value and GET Search B2B addresses.

You move a prospect between review states by updating prospectWorkflow on its CL document.

To approve a prospect, send prospectWorkflow as APPROVED together with approved as true. On a direct write to the CL document, you set approved yourself and you run the eligibility checks yourself.

A direct write does not refuse an ineligible approval. Confirm first that a prospect is eligible by following the eligibility confirmation steps mentioned above.

A prospect approved through a direct write is equivalent to one approved in the prospect review interface, which runs the same checks and will not approve while those entities are missing.

To reject a prospect, send prospectWorkflow as REJECTED and keep approved as false.

Approval provisions nothing. It creates no organization unit, no address, and no storefront user, which is why those records must already exist.

CL documents are stored in Master Data v1, where a PATCH request updates the fields you send and leaves the other fields of the document unchanged, so a transition request carries only the fields the transition changes.

For the full field list and the field descriptions, see PATCH Update contract by ID. For the partial update behavior, see PATCH Update partial document.

An approved prospect is a contract approved to operate: approved carries true, and prospectWorkflow stays as APPROVED, keeping a record of the review on the document.

Contracts created before the prospect workflow existed carry prospectWorkflow as null and are unaffected by it.

Give the buyer organization its users and permissions. See B2B user provisioning.

• B2B Contracts API
• Organization Units API
• Master Data API - v1
• B2B Addresses API
• B2B user provisioning
• B2B Buyer Portal Master Data architecture
• B2B Buyer Portal integration overview