B2B Buyer Portal is currently available to selected accounts.

VTEX B2B Buyer Portal provides a robust self-service interface for corporate buyers. It simplifies B2B complexity by allowing organizations to autonomously manage their accounts, procurement workflows, and spending limits, enhancing operational efficiency for both merchants and customers.

This guide provides an overview of the integration capabilities available in B2B Buyer Portal and the APIs that support them. Each section introduces a feature area, explains its purpose, and links to the detailed integration guide or API reference.

• Architecture overview
• Contracts
• Organization management
  • Organizational Units and scopes
  • User provisioning
  • Storefront roles and permissions
  • Buyer data
• Payment cards
• Addresses
• Budgets and allocations
• Buying policies
• Accounting fields
  • Default values
• Punchout

B2B Buyer Portal integrations are built around the following core concepts:

• Contracts sit at the root of the buyer organization. They define the commercial conditions that apply to the whole organization, such as product assortment, prices, and payment methods.
• Organizational Units represent the hierarchical structure under that root, such as departments, divisions, or subsidiaries. They are the central entity for scoping many buyer portal features.
• Storefront users are members of the buyer organization who interact with the store, each assigned specific roles and permissions.
• Storefront roles control what actions each user can perform, from placing orders to managing budgets.

Contracts establish the commercial conditions between a B2B customer and your store. They centralize purchase agreement management by defining the products buyers can access, the prices that apply to them, and the payment methods they can use.

Capability	Description
Agreement alignment	Define organization-wide conditions: assortment, pricing, and payment rules—that organizational units inherit.
Contract lifecycle	Create, update, and manage buyer contracts and keep commercial conditions aligned with negotiated agreements.

Use the B2B Contracts API to create, update, and manage contracts and their corresponding commercial conditions.

Organization management covers the structure, identity, and access control of a buyer organization. It includes creating and managing organizational units, provisioning users, assigning roles, and storing enriched buyer data.

These capabilities form the foundation of every B2B Buyer Portal integration since most other features (Budgets, Buying policies, accounting fields) operate within the context of organizational units and depend on users having the right storefront roles.

Organizational units represent the hierarchical structure of a buyer organization. A unit can be a department, division, regional office, or any other grouping that reflects how the company organizes its purchasing operations.

Each organizational unit also supports scopes, which allow administrators to restrict which attributes, such as contracts, payment methods, addresses, credit cards, collections, and accounting fields, are visible and available to users within that unit.

For more information about scopes, see Scopes overview.

Capability	Description
Create and manage units	Create, list, move, edit, and delete organizational units that represent the buyer's company structure.
Hierarchical organization	Organize units into parent-child relationships to model the company's hierarchy.
Scope configuration	Restrict which contracts, payment methods, addresses, and other attributes are available per unit.
User assignment	Link storefront users to their respective organizational units.

Use the Organization Units API to create, list, move, edit, and delete organizational units and to manage scopes.

User provisioning covers the process of creating B2B users in VTEX and linking them to organizational units. This integration is essential when onboarding buyer organizations from external platforms or ERPs and when automating user lifecycle management.

The provisioning flow includes registering storefront credentials in VTEX ID, assigning users to organizational units, granting storefront roles, and saving enriched buyer data in the Shopper entity.

Capability	Description
Create storefront users	Register users in VTEX ID with unique usernames and optional login emails.
Assign users to units	Link storefront users to their respective organizational units.
Assign storefront roles	Grant role-based permissions that control what each user can do.

The key APIs related to user provisioning are:

• VTEX ID API — Create storefront users and manage authentication identifiers.
• Organization Units API — Allocate users to organizational units.

For the full step-by-step integration, see B2B user provisioning.

Storefront roles provide a structured authorization model for B2B stores. They control which actions each user can perform, from placing orders and approving purchases to managing organizational settings and budgets.

The system ships with predefined roles (such as Buyer, Order Approver, and Organizational Unit Admin) and fine-grained resource keys that can be combined as needed.

Capability	Description
Role assignment	Assign one or more predefined roles to storefront users via API.
Permission verification	Check whether a user has access to a specific storefront resource.
Role revocation	Remove roles from users when their responsibilities change.

Use the Storefront Roles API to assign, revoke, and query storefront roles and resource permissions.

For the full list of available roles, resources, and required permissions, see Storefront Roles.

VTEX provides a dedicated API for managing enriched buyer profile data associated with B2B storefront users. Use it when you need to store, query, or update buyer-specific attributes beyond what is captured during user provisioning.

Capability	Description
Enriched profiles	Persist and maintain buyer attributes (such as name, document, and email) beyond minimal provisioning data.
Read and update	Query and change buyer profile records as your integration or back office requires.

Use the B2B Buyer Data API to manage enriched buyer profile data.

Saved payment cards are first-class data in B2B Buyer Portal: they can be tied to a contract (shared payment methods for the organization or unit) or to a shopper (personal cards for individual buyers), similar to how other entities such as budgets or users are scoped. Tokenized card data is managed through the Card Token Vault API.

Capability	Description
Tokenized storage	Store and reference payment cards securely without handling raw card data in your integration.
Lifecycle management	Add, update, list, or retire saved cards according to your checkout and Organization Account flows.

Use the Card Token Vault API to store and manage tokenized payment card data for contract- or shopper-scoped cards.

Shipping destinations, internal delivery points, and recipients support checkout and fulfillment for buyer organizations.

Capability	Description
Physical addresses	Create, search, update, and manage shipping and billing addresses for buyer organizations.
Checkout and account usage	Supply address data consumed in checkout, default values, and the Organization Account.
Delivery locations	Register internal delivery points (docks, departments, areas).
Recipients	Manage people who can be selected as shipment recipients at the organization level.

Addresses represent shipping and billing destinations. Integrations typically use the Addresses endpoints in the Master Data API v1 to create, search, update, and manage addresses used in checkout and the Organization Account.

A location is a specific delivery point within a site, such as a dock, department, or internal area. For example, freight may be consigned to the company's street address while the actual delivery is to Dock 3456. Locations are managed through the Custom Fields API. See Custom Fields integration to learn more.

Recipients are the people who can be chosen as order recipients, who will receive the shipment. At checkout, the buyer selects the recipient for the order. That person may be different from the user placing the order. Recipient records are maintained at the organization level and can be associated with addresses, so choosing a shipping address can narrow which recipients are offered. Use the B2B Recipients API to manage recipients in B2B scenarios.

Budgets allow buyer organizations to define spending envelopes and distribute them across allocations tied to specific entities such as accounting fields, users, or addresses. During checkout, the system queries applicable allocations so that orders can be funded according to the organization's financial rules.

Capability	Description
Budget provisioning	Create and manage budgets with total amounts, validity periods, auto-reset, and carry-over settings.
Allocation management	Subdivide budgets into allocations linked to specific entities (accounting fields, users, addresses).
Checkout lookup	Query applicable allocations at checkout to determine how an order should be funded.
Balance tracking	Track remaining balances and spending history through transactions and statements.

Use the Budgets API to create, update, query, and delete budgets and allocations.

For the complete integration flow, see Budgets and allocations.

Buying policies enable buyer organizations to define dynamic authorization rules that control whether orders are automatically approved, denied, or sent for manual review. The system evaluates rules hierarchically across organizational units, using a priority-based mechanism.

Capability	Description
Rule configuration	Register custom rule expressions with bypass, deny, or sequential workflow behaviors.
Hierarchical evaluation	Evaluate rules across organizational unit dimensions in priority order.
Manual authorization	Support approval or denial workflows through score-based callbacks.

Use the Buying Policies API to create and manage authorization rules and process order approval callbacks.

For details on rule evaluation, score thresholds, and required permissions, see Buying Policies.

Accounting fields is the B2B Buyer Portal feature that allows stores to capture additional business-specific information during checkout, such as Cost Center or PO Number. Fields can be applied at the order, item, or address level and support predefined option lists or free-form input.

Capability	Description
Field configuration	Define field structure, type, level, and requirements per contract.
Value management	Create predefined values for option-type fields.
OrderForm application	Apply field values to shopping carts during checkout, individually or in batch.
Integration with budgets and policies	Use field value IDs as matching criteria in budget allocations and buying policy expressions.

The key APIs for managing accounting fields are:

• Custom Fields API — Field configuration, value management, and orderForm application.
• Default Values API — Pre-configured checkout defaults.

For the full integration flow, see Custom Fields integration.

Default values allow buyer organization administrators to pre-configure checkout preferences for each organizational unit, such as the default shipping address, billing address, credit card, and accounting field selections. When a buyer logs in, the system automatically loads these defaults, reducing manual input at checkout.

Capability	Description
Default configuration	Define default addresses, credit cards, and accounting fields per organizational unit.
Automatic application	Defaults are resolved and applied to the shopper session at login.

Use the Default Values API to create, update, retrieve, and delete default value configurations.

For the complete integration flow, see Default Values integration.

Punchout enables integration between external eprocurement systems and the VTEX store, allowing procurement users to authenticate and browse the supplier's catalog directly from their procurement platform. The integration supports two authentication flows: one for users who already exist in VTEX and one for pre-authenticated users managed by the integrator.

Capability	Description
Seamless login	Authenticate procurement users into the store via one-time tokens, without manual credential input.
Pre-authenticated flow	Support delegated login for users who don't exist in VTEX, trusting the integrator for authorization.
Cart transfer	Customize the Punchout cart screen so buyers can transfer their cart back to the eprocurement system for approval, with optional per-item extensions.

Use the Punchout API to start and finish punchout login flows using one-time tokens.

For the full login integration, see Punchout login integration. For cart transfer customization, see Punchout cart integration. For a conceptual overview, see Punchout.