Technical Guide

Multi-tenant Commerce with Vendure

June 07, 2023

Martijn van de Brug

Martijn van de Brug

Founder of Pinelab

This article covers the basics on how to use Vendure as a marketplace or multitenant setup. Multitenancy means we can have multiple shops in a single Vendure instance.

So we have one database, one backend, but we can have 300 shops (or more). When we talk about a tenant, we mean an individual shop, or an individual seller in case of a marketplace.

None of these steps require any coding, everything can be done via the Vendure admin interface.

TL;DR: These are the steps you need to take:

  1. Create a channel per tenant

  2. Set permissions per tenant

  3. Channel configuration

  4. Storefront configuration

A channel per tenant

Channels are a feature of Vendure which allows multiple sales channels to be represented in a single Vendure instance. In the Channels docs you can find more information on what channels can and cannot do.

In our case, we will use the channels feature to create multitenancy: each tenant will have its own channel. There is an illustrative diagram of how this works in the multi-tenancy guide. With the right permissions, a tenant administrator will not know of any other channels. For the multitenant setup, we don't need the default channel.

  1. Login to <your Vendure server>/admin with superadmin permissions

  2. Go to Settings > Channels and create a channel:


We don't want a tenant administrator to access things outside his own environment, so we create a new role for our tenant administrator with the following permissions:

  • CRUD permissions on: Tag, Shipping method, Promotion, Payment method, Order, Facet, Customer group, Customer, Collection, Asset, Catalog

  • Read permissions on: Country, TaxCategory, TaxRate, Zone. No write access for these entities, because they are shared amongst tenants.

Don't forget to assign the newly created channel to this role before saving.

Now you can create a new administrator with username/password and assign the new "demo-admin" role to the administrator. When you log in with this user, you will notice that you cannot view the other channels anymore.

Channel configuration

Before you can use your channel, you need to set up the following:

  • Payment method - At least one payment method is needed. There is plenty of documentation on how to set up payment methods. You can write your own payment integration, or use an existing plugin.

  • Shipping method - An order always needs a shipping method. The docs explain pretty well how to create and use shipping methods.

  • Products - What is a shop without products? Add some products! Read all about it in the catalog docs.

Storefront configuration

We won't cover everything about storefronts here, because, as you might have guessed, there is a lot of documentation on it! What you do need to know, is that you need to pass the channel token as header on every request to Vendure, so that Vendure knows what channel you are addressing:

// HTTP request header { "vendure-token": "demo-token" }


There are a few things to be aware of when using Vendure in a multitenant set up:

Taxes, zones and countries are global

Taxes, zones and countries are global. You can set taxes per country, but each tenant can see all available tax rates, zones and countries. This is also why you shouldn't give a tenant admin write access to any of these entities.

Orders are bound to a channel

You cannot have an order with products of multiple channels. An order for a channel can only have products of that channel. What you can do is add products to multiple channels, or use the default channel (the default channel will always have all products).

Customers are sort of global

Tenants can not see each other's customers, but when a customer ordered on multiple channels, those channels share the same customer entity.

Example: Customer 'Joe', identified by, has placed an order in channel-1 last week, and is now placing an order in channel-3. While placing the order in channel-3, he updates his name to 'Joseph' (he is identified by his email address). will now have firstname 'Joseph' in both channel-1 and channel-3.

Get started

Create your first commerce experience with Vendure in less than 2 minutes

Vendure is a registered trademark. Our trademark policy ensures that our brand and products are protected. Feel free to reach out if you have any questions about our trademarks.


Get the latest product news and announcements delivered directly to your inbox.

© Copyright 2022 - 2024, Vendure GmbH. All rights reserved.