API Reference

VTEX Platform Overview
Store architecture

Learn how our store architecture models are tailored to meet diverse business needs.

Store architecture diagrams represent the fundamental structure for a particular project, providing a unified vision to all stakeholders and translating business needs into software components and project requirements. In this guide, we present an overview of basic store architecture models at VTEX.

There are different types and levels of architecture, but they generally work as a reference for technical and business teams. Moreover, store architectures define for all stakeholders the roles and responsibilities of each player, how different systems interoperate, and how data is transmitted between them.

To demonstrate how VTEX integrates with the ecosystem, we created VTEX reference architecture models based on common digital commerce strategies. These blueprints illustrate interactions between VTEX modules and the business, serving as a project starting point. Learn more about the structure of these models in Understanding VTEX reference architectures.

The main use cases for common scenarios are the following:

The following diagrams represent one single VTEX account and assume that the customer is using the Store Framework as a storefront solution.

Business-to-customer (B2C)

Business-to-customer (B2C) is the most common business model within VTEX customers. It serves as a foundation for other models.

The diagram below shows the main components of a B2C commerce implementation. Components highlighted in pink are offered out-of-the-box (OOTB) by VTEX, but the diagram also shows other parts that may come from customers' internal back office systems or third-party providers.

{"base64":"  ","img":{"width":1323,"height":755,"type":"png","mime":"image/png","wUnits":"px","hUnits":"px","length":346194,"url":""}}

Below is an integration flow diagram in a B2C architecture, where the asynchronous calls (not in real time) are represented by black arrows, and synchronous calls are represented by blue arrows (real time).

{"base64":"  ","img":{"width":2078,"height":1082,"type":"png","mime":"image/png","wUnits":"px","hUnits":"px","length":411986,"url":""}}

An example of an asynchronous call is the stock update, which is represented by a black arrow pointing from the ERP to the Inventory module. A real-time update of rates in a payment is represented by a blue arrow, with information exchange in both blocks. This last scenario is synchronous because it is a sensitive stage of the customer’s purchase flow.

The architecture suggested here may go beyond B2C, as you can see in the following sections.

Business-to-business (B2B) with B2B Suite

The main characteristic of a business-to-business (B2B) model is that transactions occur between two or more legal entities.

The diagram below presents an example where the business model is a B2B using the B2B Suite, which is represented within the B2B Core Modules. In this architecture, the main account acts as a marketplace for other VTEX sellers.

{"base64":"  ","img":{"width":1470,"height":679,"type":"png","mime":"image/png","wUnits":"px","hUnits":"px","length":454815,"url":""}}

The B2B Suite is a set of VTEX IO apps tailored to streamline B2B store management. This collection of apps empower the store to oversee organizations (the companies enabled to make purchases in the store), as well as other functions and permissions for storefront and checkout. For instance, the store can offer specific price tables, collections, and custom payment methods for organizations, customers can have different user roles within organizations, among other features.

The main account has more modules than the sellers, sharing just some, such as the Order Management System (OMS) and Catalog, as you can see in the diagram below.

{"base64":"  ","img":{"width":1649,"height":1364,"type":"png","mime":"image/png","wUnits":"px","hUnits":"px","length":870503,"url":""}}

Declaring these modules in the architecture not only makes the process clearer but also makes the visualization of player responsibilities easier to understand. In this case, for example, Master Data remains with the sellers because customer approval is done at the seller level.

In B2B scenarios, real-time communication between the B2B Suite and sellers is common, as the information is always up-to-date, and also for any calculations of fees and taxes at checkout, since the end customer needs to have a smooth purchasing experience.

In the diagram above you can see the synchronous communication between the Organizations component in the main account and the sellers.

Why choose this architecture?

  • Streamlined Organization management: Fosters efficient management of multiple organizations from a centralized platform by grouping storefront users into organizations and dividing them into cost centers.
  • Customized user experience: Tailor the user experience for each organization, providing personalized pricing, payment methods, and product catalogs to meet specific business needs.
  • Enhanced security and control: Assign roles and permissions to B2B customers, ensuring appropriate access levels and maintaining control over sensitive information and transactions. Learn more in the Storefront Permissions and Storefront Permissions UI apps documentation.
  • Optimized quoting system: Facilitates quote requests and its management, enhancing negotiation and ensuring accurate pricing by integrating the quote-to-order process.
  • Efficient Order Processing: Simplifies the checkout process with shared shipping addresses for cost centers, reducing errors and streamlining order fulfillment.

Learn more

Franchise accounts (Omnichannel)

This is a very common architecture model that integrates physical stores with ecommerce as franchise accounts in VTEX.

A franchise account is linked to a main account and has the following characteristics, which you can see in the reference architecture below:

  • No separate website: Franchise accounts do not have their own dedicated website, as they operate within the main account's ecommerce, effectively acting as part of a larger marketplace.
  • Customer Data Storage: Customer data is stored in the main account’s Master Data.
  • Seller Type: Each franchise account automatically functions as a white label seller within the main account.
  • Catalog: Franchise accounts inherit their catalog from the main account.
  • Logistics and OMS: Each franchise account has its own Logistics settings and performs its own Order Management.
  • Prices and Payments: Each franchise can have its own price and payment methods, or they can inherit prices and payment methods from the main account.
  • Promotions: It is possible to create promotions for each franchise account and for the main account.

{"base64":"  ","img":{"width":1242,"height":690,"type":"png","mime":"image/png","wUnits":"px","hUnits":"px","length":287077,"url":""}}

This architecture model works well for brands that have multiple physical stores, franchises, or representatives. In these cases, each physical store / franchise / representative can have a franchise account in VTEX integrated into the brand’s main account. This allows them to deliver the products sold through the brand’s ecommerce from an omnichannel perspective.

Why choose this architecture?

  • Potential to reduce the percentage of out-of-stock items.
  • More shipping options, with the potential to reduce logistics costs.
  • Physical stores can be configured as pick-up points.
  • Physical stores can function as small warehouses, operating in the ship from store strategy.
  • Possible gain from inventory reduction through the implementation of the Endless Aisle strategy, which is done by using the VTEX Sales App.

The VTEX Sales App is available in Brazil and some LATAM countries. To find out if it is available in your country, open a ticket to VTEX Support.

Multi-language and Multi-currency

Some of our customers are present in multiple countries and want to have every local store running on VTEX. We provide a multi-language and multi-currency architecture for this scenario, explained in the following sections.

Single account, multi-binding

In this architecture, a single VTEX account is configured to support multiple languages and currencies, using a multidomain approach.

The reference architecture below exemplifies its main characteristics:

  • Separated website: One single account, but each store with its own domain, bound to different trade policies by bindings.
  • Search: Search Settings are the same for all websites.
  • CMS: Shared access to Content Management System (CMS) between websites.
  • Customer Data Storage: One single Master Data for all stores.
  • Catalog: One single catalog, segmented by trade policies.
  • Logistics: Each store has its logistics operation managed by different warehouses in the same Logistics panel.
  • Order Management System (OMS): One single Order Management System panel for all stores.
  • Payments: Shared Payment settings between all stores.
  • Prices and Promotions: It is possible to configure different prices and promotions for each store, as you can segment them by trade policy. Still, prices and promotions for all stores are managed in the same panel.
  • Message Center: One single Message Center for all stores.

{"base64":"  ","img":{"width":1441,"height":693,"type":"png","mime":"image/png","wUnits":"px","hUnits":"px","length":270012,"url":""}}

This model is easier to set up, integrate, and maintain compared to the multi-account approach, but it may not be efficient for large and complex operations. This architecture is recommended for operations present in more than one country, requiring the configuration of different languages and currencies, but without the need for data segregation, as all core services are shared. Therefore, it may work well for operations managed by a single, centralized team.

Why choose this architecture?

Product names are not translated on the Checkout and My Account pages. These modules directly call the Catalog API to get product data, so the information does not pass through the Messages API.


In this architecture, one main account will act as a seller in secondary accounts that act as marketplaces.

The reference architecture below exemplifies its main characteristics:

  • Separated VTEX account: Each store has its own VTEX account.
  • Separated website: Each store has its own website and may customize its frontend with a different style per store.
  • Customer Data Storage: Segregated by marketplace account. There is no customer information within the main account’s Master Data.
  • Promotions: Promotions from the main account have limited capabilities, as every information that comes from the customer will not be accessible by the main account. For example, if you want to create promotions for a customer cluster in the main account, it will not work because it does not have access to the marketplace’s Master Data.
  • Checkout, Order Management System (OMS), Payments, and Message Center: Each store manages these modules independently in its own Admin panel, without relying on the main account.
  • Catalog, Pricing, and Logistics: The main account is the source of truth for these VTEX Core services, but the management of them are independent, as each account has its own Admin panel. The product assortment can vary between accounts but is always based on the main account's catalog, as the main account is the owner of the it.

Assembly options, attachments, and services are not supported.

{"base64":"  ","img":{"width":1398,"height":714,"type":"png","mime":"image/png","wUnits":"px","hUnits":"px","length":326503,"url":""}}

This architecture is recommended for operations in more than one country, requiring the configuration of different languages and currencies, where different teams manage each localized store.

Why choose this architecture?

  • Supports both single fulfillment (all items shipped from one account) and multiple fulfillment (items shipped from different accounts within the same purchase), ensuring efficiency by optmizing logistics based on item availability and proximity to the customer.
  • Having the seller (main account) act as catalog owner and the accounts for each country act as marketplaces enables a multi-language solution. This allows each store to manage its language and currency locally within its own store.
  • Support better translations compared to the single account, multi-binding model, as there is an independent catalog translation. Therefore, you do not need to rely on Messages or Catalog translation app.

Learn more

Photo of the contributor
+ 1 contributors
Was this helpful?
Suggest edits (Github)
See also
Understanding VTEX reference architectures
Photo of the contributor
+ 1 contributors
On this page