Multi-tenancy Support

Vendure supports multi-tenant headless commerce solutions through its powerful Channels feature.

Channels allow us to segment our business entities per tenant. To do this, you would create a separate Channel per tenant.

Creating Tenants

Let’s say we want to use a single Vendure instance to run 2 separate e-commerce businesses: Ace Parts and Best Choice. First we need to create a new Channel for each:

Do this for both of our tenants: ace-parts and best-choice.

Defining Roles

The next requirement is being able to create Administrators who have permissions only for a given tenant. This is supported by Vendure’s role-based access control system.

First we will create a new Role, and grant all permissions on the ace-parts Channel only:

Next we create a new Administrator, and assign the Role that was just created.

Repeat the steps of creating a Role and Administrator for the best-choice Channel.

Now you’ve successfully set up your two tenants and you have an admin account for each.

Mechanics of Multi-Tenancy

Each tenant is modelled as a Channel, and both of our new Channels can be considered “children” of the default Channel. That is, the default Channel contains every Product, Customer, Order, Promotion etc., no matter which Channel they were created in.

In this way, the default Channel can be used by the superadmin account to get an overview of the entire instance, whereas the admins of each tenant will only have access to the entities assigned to their respective Channels.

The following entities are “channel-aware”, i.e. they can be assigned to a specific Channel:

• Asset
• Collection
• Customer
• Facet/FacetValue
• Order
• PaymentMethod
• Product/ProductVariant
• Promotion
• Role
• ShippingMethod

In the Admin UI, you can switch between active Channels using the switcher component in the top bar:

For example, switching to the ace-parts Channel, and then creating a new Product will assign that new Product to the ace-parts Channel (and the default Channel, since everything is assigned to the default Channel).

The Storefront

Your storefront applications will need to specify which channel they are interested in. This is done by adding a query parameter or header to each API requests, with the key being vendure-token and the value being the target Channel’s token property.

https://my-vendure-server.com/shop-api?vendure-token=best-choice

Determining the Active Channel

When developing plugins and writing custom server code in general, you’ll often want to know the Channel that the current request is using. This can be determined from the RequestContext.channel property.

createPayment: async (ctx, order, amount, args) => {
  if (ctx.channel.code === 'ace-parts') {
    // Use the Ace Parts account to process
    // the payment  
  } else {
    // Use the Best Choice account to process
    // the payment  
  }
}