Marketplace Recipe
This guide shows you how to build a marketplace platform where multiple sellers can list their products for sale. You'll learn how to model products and vendors, handle fulfillment, process payments, and manage vendor relationships.
Product and Vendor Model​
In Saleor, vendors are not a built-in entity type. Instead, we implement them as custom models using Saleor's modeling system.
The marketplace architecture is built around the concept of linking products to these vendor models through attribute references. Each product can have a "Vendor" attribute reference that links to a vendor model, which can contain descriptive information like photos and bios.
Modeling Overview
Learn more about modeling in Saleor.
Attributes Overview
Learn more about attributes in Saleor.
Based on our experience with marketplace modeling, we distinguish two main approaches:
Commodity Marketplace​
A commodity marketplace, similar to Amazon's model, is designed for scenarios where multiple vendors sell the same product.
In this approach, you create a top-level "product model" that serves as the main product listing. This model contains all the descriptive information about the product, while individual vendor offers contain specific details like pricing and availability.
When building a commodity marketplace, keep in mind that you'll need to use model-based organization instead of traditional categories or collections, as the top-level products are models rather than standard Saleor products.
In this architecture:
- Product Page: Model entity that contains the main product information (description, images, specifications)
- Vendor Offer: Product entity that contains vendor-specific details (price, stock, shipping)
- Vendor: Model entity that contains vendor information (profile, bio, contact details)
Boutique Marketplace​
A boutique marketplace, exemplified by platforms like Etsy, is simpler in structure.
In this approach, each product is unique and directly linked to its vendor without the need for a top-level product model:
- Product: A Saleor Product entity that contains both product information and vendor-specific details
- Vendor: A Saleor Model entity that contains vendor information (profile, bio, contact details)
Vendor Permission Management​
Saleor's permission system doesn't have a built-in vendor entity or vendor-based permissions, so this must be implemented at the application level.
OIDC Plugin (with IdPs such as Auth0 or KeyCloak) can be used to provide authentication and issue tokens containing user permissions or roles. However, OIDC itself does not enforce which resources (e.g., products) a vendor can access or modify. Instead, the Vendor Portal application is responsible for:
- Obtaining the token from the OIDC provider when a vendor logs in.
- Reading the permissions or roles from the token.
- Enforcing business logic to ensure that vendors can only perform operations (such as updating a product) on resources they are authorized to access. For example, the Vendor Portal must check that the vendor is only able to update their own products, and not products belonging to other vendors.
This means that the security of vendor operations relies on the Vendor Portal correctly scoping all actions based on the permissions in the token.
The following diagram illustrates the flow, with the understanding that the Vendor Portal is responsible for enforcing access control:
The Vendor Portal must always validate that the vendor is only able to mutate their own products, based on the permissions in the token. OIDC alone does not prevent a vendor from attempting to update another vendor's product; this logic must be enforced in the application.
Fulfillment​
The marketplace fulfillment process is based on the vendor-product relationship. Since each product is linked to its vendor, order lines contain all necessary information for vendor-specific fulfillment. This structure enables each vendor to handle their own shipping independently.
Example​
- Get attributes from the order lines
query GetOrderLines($id: ID!) {
order(id: $id) {
id
lines {
variant {
attributes {
values {
name
inputType
reference
}
}
}
}
}
}
- Get the vendor id from the attribute reference
const vendor = order.lines.variant.attributes.values.find(
(attribute) => attribute.name === "Vendor"
);
- Fetch the vendor details
query GetVendor($id: ID!) {
page(id: $id) {
id
title
}
}
- Fulfill the order by vendor
The final fulfillment step depends on your marketplace's policy. With the vendor details, you can implement any fulfillment strategy that fits your business needs, e.g., fulfilling from the vendor's warehouse or using a central warehouse.
Warehouses
Learn about warehouse management.
Fulfillment Overview
Learn more about fulfillment in Saleor.
Shipping​
If each vendor ships their products separately, you can implement a shipping app that handles the complexity of multiple vendor shipments.
The app would sum shipping methods (including their prices) for each vendor while providing detailed shipping price breakdowns through metafields.
Payments​
Marketplace payments require a two-step process: handling customer payments and managing vendor payouts. Ideally, you would use an existing payment solution like the Stripe App for the customer-facing payment process. Once the customer payment is processed, you'll need to implement an asynchronous payout system to distribute funds to the relevant vendors, taking into account any commission fees or marketplace charges.
Feasibility of this approach depends on the marketplace's business model and the payment provider you choose. It may be necessary to implement a custom payment solution to handle the specific requirements of the marketplace.
Taxes​
Tax management in a marketplace requires handling vendor-specific tax rules. Different vendors may be subject to different tax rates based on their location or business type. To handle this complexity, you can implement a custom tax app that calculates tax rates specific to each vendor. This is particularly important for marketplaces operating across multiple regions or jurisdictions.
Vendor Portal​
Saleor Dashboard cannot be used for vendor management as it lacks vendor-specific access control. You must build a custom vendor portal from scratch as a separate application. This portal will need to:
- Interface with the Saleor API to fetch and modify data
- Implement custom authentication and authorization for vendors
- Filter and display only the vendor's own products and orders
- Provide vendor-specific views for:
- Profile management
- Product creation and updates
- Order tracking
- Sales analytics
- Discount management
The portal requires custom development because Saleor's core doesn't include a vendor entity or vendor-specific access control. You'll need to build the entire interface and implement the business logic for vendor-specific operations.
Operator Portal​
The marketplace operator portal is a separate application that marketplace administrators use to manage the marketplace. Unlike the vendor portal which is for individual sellers, the operator portal provides tools for overseeing all marketplace operations. This application must:
- Integrate with the Saleor API
- Implement custom authentication for marketplace operators
- Provide vendor management features:
- Vendor onboarding workflow
- Policy management
- Commission fee configuration
- Marketplace health monitoring
- Vendor performance tracking
The operator portal is essential for marketplace governance and cannot be implemented using the standard Saleor dashboard. It requires custom development to handle the complex requirements of marketplace administration and oversight.
Operator Portal can be a Dashboard Extension or a separate application.
Architecture Overview​
Here is a high-level overview of the essential services for a Saleor-based marketplace:
Service Descriptions:
- Saleor: The core platform, handling products, orders, and API logic.
- Storefront: The customer-facing shop interface.
- OIDC: Provides centralized permission management.
- Vendor Portal: For vendors to manage their profiles, publish products, configure shipping, and view their own sales data.
- Payment Service: Handles payment processing, refunds, integration with providers (e.g., Stripe), and payouts to vendors after sales.
- Operator Portal: For marketplace operators to onboard/manage vendors and oversee the marketplace.