Multi-Site Architecture
Learn how to build multi-site architecture with Emporix. Discover the core concepts and how they connect to enable flexible commerce across countries, brands, and customer segments.
Emporix's multi-site architecture allows you to manage multiple webshops, brands, and markets from a single platform. Understanding how sites, catalogs, categories, products, availability, and segments work together is essential for building scalable commerce solutions.
Core concepts
First, get familiar with the concepts used across this article.
Site
Definition: A Site represents a single country or country/brand combination. It serves as a virtual entity that can represent a web store, a physical store, a branded store, or a store for a specific market.
Key characteristics:
Site-aware: Each site can have its own configuration, payment methods, shipping options, and customer targeting
Independent: Sites operate independently but can share underlying resources like products and categories.
Configurable: Sites can override or augment tenant-specific configurations.
Example site codes:
Netherlands- Single country siteThermoBrand_DE- Country/brand combination (Germany, ThermoBrand brand)WarmTech_DE- Country/brand combination (Germany, WarmTech brand)
Catalog
Definition: A catalog is site-aware and manages categories for one or more sites. It acts as a container that organizes which categories are available on which sites.
Key characteristics:
Site-aware: Each catalog is published to specific sites through the
publishedSitesfield.Dynamic category assignment: Categories can be dynamically assigned to catalogs.
One catalog per site (recommended): While a catalog can be published to multiple sites, the typical pattern is one catalog per site for better organization.
Category management: Catalogs control which category trees are visible on which sites.
How it works:
When you create a catalog, you specify which sites it is published to.
You assign root categories to the catalog by specifying the
categoryIdsarray.The catalog determines which categories (and their product assignments) are visible on each site.
Category
Definition: Categories represent the hierarchical structure of products.
Key characteristics:
Not site-aware: Categories and category trees exist independently of sites - they're global resources.
Hierarchical structure: Categories form trees with root categories and subcategories.
Product organization: Products are assigned to categories to organize them.
Reusable: The same category structure can be used across multiple sites and catalogs.
Brand-specific: Typically, each brand has its own root category tree.
Benefits:
Less maintenance: Create category structure once, use it across multiple sites.
Consistency: Ensures consistent product organization across brands.
Flexibility: Easy to reorganize products without affecting site-specific configurations.
Product
Definition: Products are not site-aware - a single product instance exists globally within Emporix and can be made available on multiple sites.
Key characteristics:
Global resource: One product definition serves all sites.
Site-independent: Product attributes (name, description, images, etc.) are not tied to a specific site.
Multi-site availability: The same product can be available on different sites with different configurations.
Category assignments: Products are assigned to categories (which are then assigned to catalogs).
How products become site-specific:
While products are not site-aware, you can make them bear site-specific information. Assign products to categories and categories to catalogs. Then, publish catalogs to specific sites. To make the products visible on the storefront, define the availability for each site. Prices are site-specific, so define the product prices per each site the products appear on.
Availability
Definition: Availability is site-aware and manages product visibility and stock levels independently from category assignments.
Key characteristics:
Site-aware: Each availability record is tied to a specific site.
Independent visibility control: Controls whether a product is visible on a site, regardless of category assignments.
Stock management: Tracks stock levels, popularity, and distribution channels per site.
Granular control: Allows you to show/hide products on specific sites without changing category or catalog assignments.
Use cases:
Making a product available on Site A but not Site B.
Managing different stock levels for the same product across different sites.
Controlling product visibility based on business rules (for example, regional restrictions).
Segments
Definition: Segments are site-aware and manage visibility of products and/or categories based on the customers assignments to particular segment(s).
Key characteristics:
Site-aware: Segments are created per site (through the
siteCodefield).Role-based: Control visibility based on customer assignments.
Product and category visibility: You can control visibility of both individual products and entire categories.
Customer targeting: Customers are assigned to segments, which determines what they can see.
Use cases:
Showing premium products only to VIP customers.
Restricting certain categories to specific customer groups.
Creating brand-specific experiences for different customer segments.
How everything connects together
Understanding the relationships between these concepts is crucial for effective multi-site management:
Connection flow
Products → Categories: Products are assigned to categories to organize them logically.
Categories → Catalogs: Root categories are assigned to catalogs through the
categoryIds.Catalogs → Sites: Catalogs are published to sites through the
publishedSites.Products → Availability: Products have availability records per site (controls visibility and stock).
Products/Categories → Segments: Segments control visibility of products and categories based on customer roles.
Segments → Sites: Segments are site-specific and work within the context of a site.
Key relationships
Site ↔ Catalog
One catalog is typically published to one site (one-to-one relationship).
A catalog can be published to multiple sites if needed (one-to-many).
The catalog determines which categories are available on the site.
Category ↔ Catalog
Multiple categories can be assigned to one catalog (many-to-one).
The same category can be assigned to multiple catalogs (many-to-many).
Categories are assigned by the root category IDs.
Product ↔ Category
Products are assigned to categories (many-to-many).
A product can belong to multiple categories.
A category can contain multiple products.
Product ↔ Availability
Each product can have multiple availability records (one per site).
Availability is site-specific and controls visibility independently.
Product/Category ↔ Segments
Segments can control visibility of both products and categories.
Segments are site-specific.
Customers are assigned to segments, which determines what they see.
Architecture patterns
Pattern 1: Single site, multi-brands
Use case: One country with multiple brands sharing the same site.
Example: Netherlands Setup
Pattern 2: Multi-site, segmented brands
Use case: Multiple sites, each dedicated to a specific brand.
Example: Germany setup
The multi-site architecture pattern is most relevant when you want to run different webshops per country or country/brand combination. It provides multi-market support and brand separation, along with operational efficiency through reduced maintenance and flexibility (independent configuration, granular control).
Single site vs multi-sites patterns comparison
Single site
Multi-sites
How it works
All brands share the same site.
Each brand has its own dedicated site.
One catalog contains all brand category trees.
Each site has its own catalog.
Products from different brands are organized under their respective category trees.
Each catalog contains only the relevant brand's category tree.
Availability controls which products are visible on the site.
Products are made available on specific sites by respective availability records.
Segments can further restrict visibility based on customer roles.
Segments work independently per site.
Advantages
Simple setup for single-country operations.
Brand separation and independence.
All brands accessible from one storefront.
Different customer experiences per brand.
Easy to manage shared resources.
Independent site configurations (payment, shipping, etc.).
Better for brand-specific marketing and promotions.
Site-aware carts and orders help avoid mixed-brand orders and enable brand identification.
Practical examples
Example 1: Setting up Netherlands (single site, multi-brands)
Create the site
Create the Netherlands site by sending a request to the Creating a site endpoint.
To test the endpoint, open the API reference or check the example of a curl request.
Create category trees for each brand
Create root categories for each brand you sell. These categories can be used across multiple sites.
Call the Creating a new category endpoint to create two root categories.
To test the endpoint, open the API reference or check the example of a curl request.
ComfortHeat:
WarmTech:
Copy the IDs of the created categories.
The same way, create subcategories for each root brand category, for example: Heaters, Boilers or similar, providing the relevant parentid in the request.
Create the catalog and assign categories
Create a catalog for the Netherlands site and assign the brand category trees to it by passing the IDs of the created categories. Send the request to the Creating a catalog endpoint.
To test the endpoint, open the API reference or check the example of a curl request.
Assign products to respective categories
Call the Assigning a resource to a category endpoint to assign selected products to the Thermobrand and WarmTech categories. Pass the respective categoryId as the path parameter.
To test the endpoint, open the API reference or check the example of a curl request.
Create availability for products
Create availability records for the products on the Netherlands site to control visibility and stock levels. Send the request to the Creating a new availability for a product endpoint passing the relevant productId and the site as the path parameters.
To test the endpoint, open the API reference or check the example of a curl request.
Example 2: Setting up Germany (Multi-Site, segmented brands)
Create sites
Create separate sites for each brand in Germany so that each brand has its own dedicated site. Use the Creating a site endpoint.
To test the endpoint, open the API reference or check the example of a curl request.
Create
ThermoBrand_DEsite:
Create
WarmTech_DEsite:
Create catalogs for each site
Create a dedicated catalog for each site and assign only the relevant brand's category tree to each catalog. Call the Creating a catalog endpoint.
To test the endpoint, open the API reference or check the example of a curl request.
Create
ThermoBrand_DEcatalog:
Create
WarmTech_DEcatalog:
Create site-specific availability
Create availability records for products on each site to control visibility and stock levels independently. Call the Creating a new availability for a product endpoint passing the relevant productId and the site as the path parameters.
To test the endpoint, open the API reference or check the example of a curl request.
Availability for
ThermoBrand_DEsite:
Availability for
WarmTech_DEsite:
Create site-specific segments
Create customer segments for each site to control visibility based on customer roles and IDP roles. Use the Creating a customer segment endpoint.
To test the endpoint, open the API reference or check the example of a curl request.
Create segment for
ThermoBrand_DE:
Once the specific segments are created, you can assign relevant products and/or categories, as well as specific customers using the Customer Segments Service API.
Common use cases
These are some common examples how you can implement your storefront sites.
Regional product availability
Scenario
You have a product that you want to be available in certain countries due to regulations.
Solution
Create availability records only for the sites where the product should be available. The product won't appear on sites without availability records.
Brand-specific storefronts
Scenario
Each brand needs its own dedicated storefront with brand-specific categories.
Solution
Create separate sites for each brand (e.g., ThermoBrand_DE, WarmTech_DE). Create separate catalogs for each site and assign only the relevant brand's category tree to each catalog.
Premium customer access
Scenario
You want certain products to only be visible to premium customers.
Solution
Create a segment for premium customers on the relevant site. Assign premium products to the segment and assign premium customers to the segment. The products will only be visible to customers in the segment.
Multi-brand on a single site
Scenario
Multiple brands need to co-exist on the same storefront.
Solution
Create one site for all brands and one catalog for the site. Assign all brand category trees to the catalog. Organize products under their respective brand categories.
Best practices
Catalog organization
One catalog per site
For clarity and easier management, create one catalog per site.
Root category assignment
Only assign root categories to catalogs, not subcategories.
Category reuse
Reuse category trees across multiple catalogs when appropriate.
Site naming
Clear naming convention
Use descriptive site codes (e.g., ThermoBrand_DE instead of site1).
Consistent patterns
Follow a consistent naming pattern across all sites.
Country/brand format
Use Country or Brand_Country format for clarity.
Category structure
Brand-specific roots
Create separate root categories for each brand.
Hierarchical organization
Use subcategories to organize products within brand trees.
Global categories
Remember categories are global - design them to work across sites.
Availability management
Site-specific records
Create availability records for each site where products should be visible.
Stock synchronization
Keep stock levels synchronized across sites if needed.
Visibility control
Use availability to control product visibility independently from categories.
Segment
Role-based access
Use segments to implement role-based product/category visibility.
Customer assignment
Assign customers to segments based on business rules.
Last updated
Was this helpful?