=� Use this project, contribute to it or open issues to help evolve it using Store Discussion.

B2B Organizations

9 The B2B Organizations app is part of VTEX�s B2B Suite solution: a collection of apps that allow stores to manage organizations, storefront roles and permissions, and checkout settings for B2B commerce relationships. We recommend that you use it alongside the other apps in this suite for all functionalities to work as expected.

In the B2B model, sales goals go beyond a high order conversion rate. They include simplifying the relationship between companies, reducing costs, and increasing performance by providing the customer with the best possible shopping experience.

B2B commerce relations are usually complex and often require a customized service. Therefore, grouping different users from the same company under an organization, and defining custom payment methods, product selections, and prices for each customer are common tasks in this scenario.

The B2B Organizations app enables you to group B2B users into organizations. You can assign specific payment methods, price tables, and product collections to each organization, allowing all of the organization�s users to share the same commercial conditions. Each organization is further segmented into one or more cost centers, with its own shipping addresses.

Before you start

First, make sure you have the VTEX IO CLI (Command Line Interface) installed in your machine.

Note that installing B2B Organizations will also result in Storefront Permissions being installed as a dependency app � it allows you to grant specific storefront roles for B2B users in an organization. This is especially useful for organizations with multiple users who have different responsibilities, such as placing orders, approving orders or managing the organization users. See the Storefront Permissions app documentation for information on the available roles and how to customize their permissions.

If you want to be able to manage roles and permissions on the VTEX Admin, you must install Storefront Permissions UI as well.

Installation

You can install the B2B Organizations app by running vtex install vtex.b2b-organizations in your terminal, using the VTEX IO CLI.

User widget configuration

To enable the user widget in your storefront, this app provides a b2b-user-widget block that you can add to the account's store theme. We recommend that you add it to the store header, as shown below.

Follow the instructions below to display the user widget.

1. Open your store theme app�s repository in your local files.

2. In the manifest.json file, under dependencies, add "vtex.b2b-organizations": "1.x", like so:

   "dependencies": {
       "vtex.b2b-organizations": "1.x"
     },

3. Within your store theme's store > blocks > header folder, edit the header.jsonc file, placing the b2b-user-widget block in the desired location, as exemplified below.

   We recommend placing it on the top row of the store header. The b2b-user-widget block accepts no props.

   "header-layout.desktop": {
       "children": [
         "flex-layout.row#0-desktop",
         "flex-layout.row#1-desktop",
         "flex-layout.row#2-desktop",
         "flex-layout.row#3-desktop",
         "sticky-layout#4-desktop"
       ]
     },
   
     "flex-layout.row#0-desktop": {
       "children": ["b2b-user-widget"],
       "props": {
         "fullWidth": true
       }
     },

4. Publish and install the modified store theme. You can follow our documentation on Making your theme content public to do so.

Configuration

if we have only one associated organization:

if we have more than one associated organization:

b2b-user-widget

Prop name	Type	Description	Default value
showDropdown	Boolean	controls whether we are viewing the dropdown if we have more than one organization associated with the same email.	true

Customization

In order to apply CSS customizations in this and other apps, follow the instructions on Using CSS Handles for store customization.

CSS handles are available for the Organization Request Form component and the User Widget component.

CSS Handles
newOrganizationContainer
newOrganizationInput
newOrganizationAddressForm
newOrganizationButtonsContainer
newOrganizationButtonSubmit
userWidgetContainer
userWidgetRow
userWidgetItem
userWidgetButton
userWidgetImpersonationItem
userWidgetImpersonationButton
userWidgetImpersonationError

How the app works

The B2B Organizations app adds the following functionalities and components to your VTEX store, divided into VTEX Admin, Master Data v2, and Storefront capabilities:

Public	Availability	Location	Feature
B2B store administrator	VTEX Admin	Organization Requests page	Review Organization Requests
		Organizations page	Manage Organizations
		Organization Details page	Manage Cost Centers associated with organizations
			Manage Collections associated with organizations
			Manage Payment Terms associated with organizations
			Manage Price Tables associated with organizations
			Manage organization Users
		Message Center Templates page	Manage email templates related to the B2B Organizations app
B2B store administrator or developers	Master Data v2	Master Data API v2	Retrieve and edit information on organization requests, organizations, and cost centers stored in Master Data v2
B2B customer (organization user) with required permissions	Storefront	Storefront form	Request New Organization
		My Organization	Manage Organization
			Manage Cost Centers
			Manage Users
			Impersonate Users
		Storefront navigation	User Widget

9 This app can also be used together with B2B Quotes, allowing order quotes to be managed at the organization level. Please read our B2B Quotes documentation for more details.

VTEX Admin

After installing and setting up the B2B Organizations app, its VTEX Admin capabilities can be found by accessing Account Settings > B2B Organizations & Cost Centers.

Organization Requests

To request the creation of an organization, B2B customers must fill in the Request New Organization form.

Once this step is done by the customer, B2B store administrators may review the organization request by going to VTEX Admin > Account Settings > B2B Organizations & Cost Centers > Organization Requests (or at /admin/b2b-organizations/requests).

In this page, they can view a list of all the organization requests placed in their store.

Each organization can have a status of pending, approved or declined. Pending requests are the ones that still need review.

To review a request, you must:

1. Click on a request from the table � or click on > View.
2. Write a comment on the Add note field, if necessary.
3. Click on Approve or Decline.

Upon approval, the request status will change to Approved and the organization will be created. The Organization Admin and the Sales Admins will be notified about this via email. You can learn more about this notification in the Email templates section. In addition, the user designated as the Organization Admin will be granted access to the My Organization tab on the My Account page of your storefront.

If the organization request is declined, the request status will be changed to Declined and the organization will not be created. The user designated as the Organization Admin is notified via email of this result. Read more about this notification in the Email templates section.

Organizations

The Organizations page includes a list of all the organizations created in your store and their respective status, and also allows store administrators to:

• Add organizations.
• Access the Organization details page, which includes organization data, cost centers, collections, payment terms, price tables and users.

To access the page, go to Account Settings > B2B Organizations & Cost Centers > Organizations in the VTEX Admin (or at /admin/b2b-organizations/organizations).

You can click Refetch to refresh the organizations list on this page, fetching information about recently created organizations.

It is possible to use the search bar to find an organization by name or filter the organizations by status.

Each organization can have one of the following statuses:

• Active: the organization has been approved by the store administrators and it is currently active.
• On hold: the organization is currently paused, which means its users are not allowed to complete purchases at the moment.
• Inactive: the organization has been deactivated by the store administrators, so its users will not be able to login.

Add organization

You can manually create a new organization on the Organizations page. Follow these steps to do so:

1. Click on the New button.
2. Fill in the required information about the new organization, as illustrated in the image below.
   • Name of organization: name of the organization you want to create.
   • Name of cost center: name of the initial cost center associated with the organization.
   • Country: country where the cost center is located.
   • ZIP: postal code of the cost center address.
   • Address Line 1: primary address information, including street number and street name where the cost center is located.
   • Address Line 2: optional field for additional address information.
   • City: city where the cost center is located. This is filled in automatically based on the ZIP code informed.
   • State: state where the cost center is located. This is filled in automatically based on the ZIP code informed.
   • Receiver: name of the person that will receive orders in the informed address.
3. Click on Add.

9 Additional cost centers and addresses may be added after creating the organization, as explained in the next section of this documentation.

Organization Details

In the Organizations Details page, you can see and edit the information of an existing organization:

• Organization Name and Status
• Cost Centers
• Collections
• Payment Terms
• Price Tables
• Users

You can access this page by going to Account Settings > B2B Organizations & Cost Centers > Organizations in the VTEX Admin and clicking on the organization whose details you want to view, or on > View.

9 Note that assigning collections, payment terms, and price tables to an organization is optional. If these are not assigned, users of the organization will see the store�s default catalog, have access to all payment methods, and see the store's default pricing.

Organization Name and Status

In the top section of the page, you can view the following information:

• Organization Name: name of the organization. This information can be edited.
• Status: status of the organization. You can set it to Active, On Hold or Inactive by selecting from a list.
• Created: date when the organization was created.

Cost Centers

In the Cost Centers section, you can view all the cost centers associated with the organization. VTEX Admin users can view and manage cost centers for any organization.

9 Each organization must have at least one cost center.

By default, each cost center will allow all of the payment terms that have been assigned to the parent organization. However, Organization Admin users have the ability to enable or disable individual payment terms at the cost center level � see Manage Cost Centers for more information on this.

To create a new cost center, follow the steps below.

1. Click on the New button.
2. Fill in the required information about the new cost center, as illustrated in the image below.
   • Name: name of the cost center.
   • Country: country where the cost center is located.
   • ZIP: postal code of the cost center address.
   • Address Line 1: primary address information, including street number and street name where the cost center is located.
   • Address Line 2: optional field for additional address information.
   • City: city where the cost center is located. This is filled in automatically based on the ZIP code informed.
   • State: state where the cost center is located. This is filled in automatically based on the ZIP code informed.
   • Receiver: name of the person that will receive orders in the informed address.
3. Click on Add.

Cost Center Details

You can view or edit the details of an existing cost center by clicking on it in the Organization Details page.

This will lead you to the Cost Center Details page, where you can:

• View or edit the cost center�s Name and Addresses.
• View or edit the cost center's Business Document.
• Add a new shipping address associated with the cost center.
• Delete the cost center

The optional Business Document field may be used to store a Tax ID, VAT ID, CNPJ, or similar business identifier. If a Business Document is present in a user's cost center, it will be applied as the corporateDocument in the user's profile and therefore attached to any orders placed by the user.

�� The shipping addresses assigned to a cost center will be available to that cost center's users at checkout if you install B2B Checkout Settings. No other addresses will be available. Therefore, each cost center must have at least one shipping address.

To edit or delete an existing address, click next to it and select Edit or Delete.

If you would like to add a new shipping address related to that cost center, follow these instructions:

1. Click on Add new address.
2. Fill in the required information about the new address.
   • Country: country where the cost center is located.
   • ZIP: postal code of the cost center address.
   • Address Line 1: primary address information, including street number and street name where the cost center is located.
   • Address Line 2: optional field for additional address information.
   • City: city where the cost center is located. This is filled in automatically based on the ZIP code informed.
   • State: state where the cost center is located. This is filled in automatically based on the ZIP code informed.
   • Receiver: name of the person that will receive orders in the informed address.
3. Click on Add.

Make sure to click Save in the top right of the Cost Center Details page after any changes.

If you want to delete the cost center, click on Delete instead.

Collections

9 You must use the Collections Beta solution to be able to associate collections to organizations using B2B Organizations. Read our article on Creating Collections Beta for more information.

This section allows you to manage the product collections assigned to the organization. Your selections define the assortment of products the organization users will see in the storefront.

To add a collection, select the collection you want to add from the Available list and click Add to org.

To remove a collection, select the collection you want to remove from the Assigned to organization list and click Remove from org.

Payment Terms

In this section, you can choose which payment conditions are assigned to the organization. Your selections determine which payment options are available to organization users during checkout.

Note that the available payment options can be further customized per cost center by the Organization Admin. Check the Manage Cost Centers section for more information on this.

To add a payment term, select the option you want to add from the Available list and click Add to org.

To remove a payment term, select the option you want to remove from the Assigned to organization list and click Remove from org.

9 To customize the checkout according to each organization user�s role, you need to install and configure B2B Checkout Settings.

Price Tables

This section allows you to choose which price tables are assigned to the organization. The price tables you select determine the prices the organization users will see in the storefront.

To add a price table, select the option you want to add from the Available list and click Add to org.

To remove a price table, select the option you want to remove from the Assigned to organization list and click Remove from org.

Users

This section presents a list of users associated with the organization, showing their Email, their Role in the organization and the Cost Center they are associated with.

To add a new user to the organization, follow these steps:

1. In the Users list, click on the New button.
2. Fill in the user�s information, as illustrated below.
   • Name: full name of the user.
   • Email: email of the user.
   • Cost Center: cost center the user will be associated with.
   • Role: role the user will have in the storefront. See more details on the available roles in the Storefront Permissions documentation.
3. Click on Add.

Once you add a new user to the organization, if a customer account did not already exist in your store for the provided email address, it will be created.

To edit or remove an existing user, follow these steps:

1. Click on the user you want to edit or delete in the Users list.

2. Edit the desired information.

   You can change the user�s Cost Center and their Role.

   If you want to remove the user from the organization, click Remove user instead and skip the next step.

3. To apply your changes, click Save.

If a user is removed from an organization, their account will continue to exist in the store, but they will no longer be assigned to an organization, a cost center, and a B2B role. Thus, they will no longer have access to details of their organization in the My Organization page. Instead, they will have the ability to request the creation of a new organization, if necessary.

9 As an optional feature, you can install the Admin Customers app for additional customer management capabilities on the VTEX Admin.

Email templates

The B2B Organizations app provides a set of four email templates to be sent to B2B organization users, triggered automatically based on specific changes:

Template name	Recipient	Trigger
Organization Approved	User with the Organization Admin role	The organization request has been approved.
Organization Created	Users with a Sales Admin role	The organization has been created.
Organization Declined	User with the Organization Admin role	The organization request has been declined.
Organization Status Changed	Users with the Organization Admin role	The organization status has changed.

If you want to view or edit any of these templates, follow the steps below.

1. In the VTEX Admin, go to Customer > Message center > Templates.
2. In the search bar, type organization.
3. Click on the template you want to view or edit.
4. Make the desired changes in the template. You can learn more about editing Message Center templates by reading our documentation on How to create and edit transactional email templates.
5. Click on Save.

Master Data v2

The B2B Organizations app stores information about organization requests, organizations, and cost centers in Master Data v2.

This means that it is possible for store administrators or developers to fetch this information using the Master Data API v2, by using their data entity name as the value for the data_entity_name parameter.

You can see the data entity names in the table below.

Data entity names
organization_requests
organizations
cost_centers

Storefront

Storefront capabilities, in turn, are accessible to B2B customers who visit a supplier�s store, provided that they are logged in and have the required permissions.

The following sections describe what your customer can do in your storefront, after you've finished setting up the B2B Organizations app.

Request New Organization

A B2B user who is not already part of an organization can request the creation of a new buyer organization in your store by filling in the Request New Organization form. They can follow the steps below to do so.

1. Access the store website.
2. Click on My Account > My Organization.
3. Provide the required information, as shown in the image below.
   • Organization Name: name of the organization.
   • User to become Organization Admin: section where you must provide information about the first user of the organization, who will be assigned as the Organization Admin.
     • First Name: first name of the Organization Admin user.
     • Last Name: last name of the Organization Admin user.
     • Email Address: email address of the Organization Admin user.
   • Default Cost Center: section where you must provide information about the first cost center associated with the organization.
     • Cost Center Name: name of the cost center.
     • Business Document: optional field for a business document such as a Tax ID, CNPJ, etc.
     • Country: country where the cost center is located.
     • ZIP: postal code of the cost center address.
     • Address Line 1: primary address information, including street number and street name where the cost center is located.
     • Address Line 2: optional field for additional address information.
     • City: city where the cost center is located. This is filled in automatically based on the ZIP code informed.
     • State: state where the cost center is located. This is filled in automatically based on the ZIP code informed.
     • Receiver: name of the person that will receive orders in the informed address.
4. Click Submit.

After submitting the form, the request will be sent to a queue for review by the B2B store administrator � for more details on this, refer to the Organization Requests section.

The user designated as the Organization Admin for the new organization will receive an email notification when the request has either been approved or declined by the store administrator. You can learn more about this notification in the Email templates section.

My Organization

Users who are designated as the Organization Admin or Sales Admin can manage the details of their organization in the storefront, on the My Organization page.

Users with the Organization Buyer or Organization Approver roles can also view a read-only version of this page.

To access My Organization, follow the instructions below.

1. Access the storefront and log in.
2. Click Hello, {name}.
3. Click on My Account.
4. Go to My Organization on the sidebar. You will see the page below.

On this page, the user with the Organization Admin or Sales Admin roles may do the following:

• Manage Cost Centers
• Manage Users

Manage Cost Centers

Organization Admin or Sales Admin storefront users can find the cost centers associated with their organization in the Cost Centers section of the My Organization page.

To add a new cost center, they should go to My Account > My Organization, where they have access to the same options described in Cost Centers. It is possible to view or edit the details of an existing cost center by clicking on it, the same way as described in Cost Center Details.

Organization Admins may also view and/or edit the Business Document assigned to each cost center, as described in Cost Center Details.

In addition, Organization Admins can enable specific payment terms for a cost center, by using the toggle button to activate or deactivate the payment terms assigned to the organization, as shown below.

�� This section will only be available on the My Organization page if payment terms have previously been assigned to the organization by the VTEX Admin users.

Manage Users

Organization Admin or Sales Admin storefront users can also see and manage the users of their organization in the Users section in My Organization. To do this, they should go to My Account > My Organization, where they have access to the same options described in the Users section of this documentation.

Users with the Organization Admin role may add, edit, or remove users with any of the following roles: Organization Admin, Organization Approver, and Organization Buyer.

Users with the Sales Admin role may add, edit, or remove users with any of the following roles: Sales Admin, Sales Manager, and Sales Representative.

Impersonate Users

In telesales, assisted sales, or customer support scenarios where the B2B customer needs help from a salesperson to navigate the store or place orders, it is common to make use of impersonation.

In the B2B Organizations app, only users with Sales roles or the Organization Admin role may impersonate another user.

This action will temporarily apply the impersonated user's email, organization, and cost center to their storefront session. It allows the impersonating users to do the following:

• Browse the store and see the prices, products, shipping addresses and payment methods that would be seen by the impersonated user.
• Take actions on behalf of the impersonated user, such as placing orders.
• Use their regular permissions.

To use impersonation, users with Sales roles or the Organization Admin role must follow the steps below.

1. In the Users section of My Organization, click on in the row of the user they want to impersonate.
2. Click on Impersonate User.

User widget

To give storefront users visibility into their currently assigned organization, cost center, and role, this app provides a user widget which can be added to the account's store theme:

9 To display the user widget, it is necessary to follow the instructions in the User widget configuration section.

If users click Manage organization, they can access the My Organization page directly.

In case impersonation is currently active, this block will also show the email of the user being impersonated, as well as a Stop impersonation button:

Contributors (

Thanks goes to these wonderful people:

This project follows the all-contributors specification. Contributions of any kind are welcome!

Upcoming documentation:

• [B2BORG-96] Fix duplicate check