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

This guide explains how merchants can migrate their B2B user base from external platforms to VTEX in a secure way, including how to:

• Register new users in VTEX ID with unique login credentials.
• Create and manage organizational units for buyer users.
• Link users to their respective organizational units.
• Assign administrative roles and permissions to users.
• Save detailed user information in the Shopper entity.

Before provisioning B2B users in VTEX, make sure the required features are enabled and the appropriate permissions are configured:

• The Storefront Permissions feature is enabled for your account. Requests to accounts without this feature enabled will receive a 403 Forbidden response.
• Any user or API key must have an admin role containing the appropriate License Manager resources to successfully run requests listed in the table below. Otherwise, the requests will return a 403 error.

Product	Category	Resource	Associated endpoints
VTEX ID	User Management	Create User	POST Create storefront user with username
Organization Units	Units	Edit Organization Unit	POST Create organizational unit POST Assign user to organizational unit
License Manager	Services access control	Edit Storefront User Permissions	POST Assign storefront roles to user
Dynamic Storage	Dynamic storage generic resources	Insert or update document (not remove)	POST Create new document

For effective authentication, every B2B buyer must comply with the following:

• The username must be unique within the store.
• The user must be linked to an organizational unit.
• The user's organizational unit must be linked with at least one valid contract.
• The user must be registered in the Shopper entity in Master Data v2.
• If the user signs in with an email, they must have a valid email address registered in the Shopper entity to receive an access code when defining or recovering their password.

The user provisioning process follows these main steps:

1. Create storefront user with username: Register new storefront users in VTEX ID with unique login credentials.
2. Create organizational unit: Create organizational units where storefront users will be assigned.
3. Assign user to organizational unit: Link storefront users to their respective organizational units.
4. Assign storefront roles to user: Assign storefront roles and permissions to users.
5. Save buyer data: Register detailed user information in the Shopper entity.

At this stage, the created user is not yet linked to an organizational unit, nor do they have storefront permissions.

Register a new user in VTEX ID. You must create this user with a required username, which remains the primary login identifier for the storefront. The username is a case-insensitive field that accepts 3 to 70 characters, including special characters (except whitespace).

Optionally, you may also register a login email for the user. When provided, the user can use this email address as an alternative login identifier to authenticate using either their username or their login email address. This same login email will also be used for password recovery.

The login email address defined in this step is different from the email address collected in Step 5, which is used exclusively for transactional communications and does not affect authentication or password recovery.

At this stage, the created user is not yet linked to an organizational unit, nor do they have storefront permissions.

Parameters:

• identifiers: List of login keys, indicating their type and value.
• isLegacyPassword: Indicates whether the user should recover their password through an external service (true) or define a new password on their first login (false, default).

For more information, see POST Create storefront user with username.

Once you create a user, you can’t edit or remove it. If you upload incorrect data, create a new user with a new username.

This step is required only if the storefront user's organizational unit does not exist yet. If it already exists, proceed to Step 3 - Assign user to organizational unit.

Organizational units identify the organizations that buyer users are part of. All new units are created at the root level. To create child-level units, see POST Move organizational unit.

For more information, see POST Create organizational unit.

Links a user to an organizational unit, establishing their organizational membership.

For more information, see POST Assign user to organizational unit.

Storefront users can have roles in their organizations. This endpoint assigns the role(s) the user will have within their buyer organization.

Each storefront role has a unique roleId (integer). The available roles and their permissions are:

Role ID	Storefront role	Associated resources
1	Organizational Unit Admin	ManageOrganizationAndContract
2	Order Approver	ApproveOrders
3	Order Modifier	ModifyOrders
4	Buyer	PlaceOrders
5	Personal Cards User	UseAdHocCard, SavePrivateCard
6	Contract Manager	ViewMyContractOrders
7	Buyer Organization Manager	ViewMyOrgUnitOrders
8	Contract Viewer	ViewProfile, ViewMyCards, ViewAddresses
9	Address Manager	ManageAddresses

For more information about available storefront roles and permissions, see Storefront Permissions. For the complete endpoint reference, see POST Assign storefront roles to user.

Buyer data is the source of truth for enriched profile information, such as first and last name, document, phone number, email, and other details. This endpoint allows you to save enriched user information.

In this context, the email address saved in buyer data is used exclusively for operational and transactional account actions, such as account activity, transaction status updates, and other order-lifecycle messages.

This transactional email is different from the login email defined in Step 1, which is used for authentication and password recovery.

For more information, see POST Create new document.

For additional user and organizational management operations, see the following API references:

• GET Get user by identifier
• GET Get organizational units
• GET Get users from organizational unit
• GET Verify user roles
• GET Get buyer data
• PATCH Edit organizational unit
• POST Move organizational unit
• DELETE Delete organizational unit
• DELETE Remove users from organizational unit