Case study - SaaS Marketplace based on Medusa

SaaS Marketplace required a completely new payment system to be built from scratch, designed to support a marketplace model. This meant not only handling customer payments but also managing the flow of funds between multiple sellers and the platform.

The solution needed to allow transactions between customers and multiple vendors, with a system that could handle dividing payments and track earnings for each vendor in real-time.

In addition to standard one-time purchases, SaaS Marketplace wanted to offer its vendors the ability to create subscription-based pricing.

Flexibility was key, and the platform needed to support usage-based pricing models. Vendors should be able to monetize their software based on how much their customers use it.

With expansion in mind, the system needed to be scalable. SaaS Marketplace envisioned growth on a global scale, so the platform had to handle increasing user demands, transaction volumes, and product listings without sacrificing performance.

The global nature of SaaS Marketplace required the integration of a tax system that needed to automatically calculate and apply taxes based on the customer’s location, following international tax rules.

We extended Medusa’s capabilities to integrate with Stripe. This allowed for smooth payment processing, and subscription handling.

We used Stripe Connect’s APIs to handle payment flows required for multi-vendor transactions. This allowed for efficient management of payments between customers and vendors, including splitting and tracking revenue.

We developed a system to automatically manage payouts to vendors. This system accounted for subscriptions, usage-based fees, platform fees, and taxes.

We set up Stripe Subscriptions to allow vendors to sell their products with subscription plans. This gave both vendors and customers more flexibility in how they manage and pay for products. Our solution supports diverse pricing models:

Created tiered subscription plans in Stripe

Implemented usage tracking and reporting from Medusa to Stripe

Instead of using Stripe’s built-in automated billing for usage-based pricing, the client wanted full control over the process. So, we replicated Stripe's functionality within Medusa, enabling the client to handle usage tracking and invoicing directly through the platform.

We implemented usage tracking by creating a custom endpoint in our API, where vendors could send data on how much of their product or service (e.g., GBs of data) their customers had used. This allowed vendors to report usage in real-time.

Once a month, our system gathered all this usage information from the vendors. Based on that data, we generated invoices for the customers, calculating their charges for the usage over the month. These invoices were then processed through Stripe.

Developed a flexible pricing engine to combine subscription and usage fees

We developed a flexible pricing engine that allowed vendors to define multiple pricing models for the applications they sold on the platform. This system gave vendors the ability to offer:

1. Fixed one-time payments: Vendors could set a single, upfront price for their application, allowing customers to purchase the app outright.

2. Subscription plans: Vendors could create subscription models with monthly or yearly billing cycles. They also had the option to offer trial periods, letting customers test the product before committing to a full subscription.

3. Subscription + usage-based pricing: This model combined a fixed monthly subscription with usage limits. For example, a vendor could charge $20 per month for their app (e.g., an image generation tool) and include 100 image generations as part of that fee. If a customer exceeded the 100-image limit, additional usage charges would apply. For instance, if the vendor set a rate of $0.50 per additional image, and the customer generated 110 images in a month, the invoice would include the $20 subscription fee plus an extra $5 for the 10 additional images.

It gave vendors more control over how they monetize their products, catering to a variety of customer needs.

Some of SaaS apps were intended to use AI and therefore required a custom billing approach, which included metered billing. Stripe’s metered billing feature was utilized to allow for usage-based pricing models. This gave vendors the ability to charge customers based on actual usage, offering more adaptable monetization options.

Stripe Tax was integrated to automate tax calculations, ensuring compliance with international tax regulations. This eliminated the complexity of managing tax rates across different regions.This approach:

• Implemented collection for transactions across different regions.
• Integrated tax reporting capabilities to simplify compliance and reporting processes.

We implemented Stripe’s pre-built, hosted onboarding process for sellers. This approach:

• Simplified compliance with KYC/AML regulations.
• Reduced development time by using Stripe’s secure, pre-designed UI.
• Ensured a consistent and secure onboarding experience.

To maintain data consistency between the marketplace and Stripe:

• We created a webhook handling system to manage the high volume and variety of events from Stripe. This system includes event prioritization, retry logic for failed webhook deliveries, and a custom dashboard for monitoring and troubleshooting webhook activities.
• We implemented error handling and retry mechanisms for any failed synchronization events, ensuring data integrity across the platform.

To ensure the platform could handle high transaction volumes, we implemented database indexing and caching strategies in Medusa, improving performance and scalability.

We developed a product review system where users could:

• Review each product individually.
• Leave ratings, write reviews, and attach images.
• Participate in threaded discussions and report reviews.
• The section is paginated and can be sorted for reviews of a specific product by rating, date, number of likes, or number of images added.

Additionally, we implemented advanced moderation tools for marketplace admins. An admin can enter any product from the storefront and directly moderate the specific review section. They can:

• Delete reviews
• Ban users from a review section
• Freeze or hide review sections

Vendors can also moderate their product review section and engage with the community. From the vendor panel, they can:

• Reply to user reviews
• Edit or delete their replies
• Report reviews to admins

This system addresses the client's requirements while promoting user interaction and maintaining content quality through moderation measures.

Recognizing the need for a centralized solution to manage all authentication data in one place as the single source of truth, we implemented Keycloak as our OAuth2 server across all components of the platform.

This ensures that user data remains up-to-date, synchronized, and secure across the storefront, vendor panel, admin interface, and third-party applications.

Each vendor is assigned a unique set of OAuth2 credentials. This configuration grants vendors read-only access with a limited scope, reducing the risk of security breaches.

Our solution provides three approaches for handling vendor authentication:

1. Integration with Vendors' OAuth2 Providers: Vendors can integrate their existing OAuth2 providers, such as Auth0 or Clerk, with our platform. This allows them to maintain their current authentication systems while interacting with the marketplace's infrastructure.

2. Simple OAuth2 Redirection via Marketplace: For vendors without their own OAuth2 providers, we offer a solution where they can add a button on their application that redirects users to the marketplace’s OAuth2 server.

3. Callback URL: This flow works as follows:

1. A user makes a purchase.
2. The user clicks a link to access the vendor's application from the marketplace.
3. They are redirected to the vendor's application, receiving an authorization code in the URL.
4. The application exchanges the code for an authorization token from the Keycloak.
5. Keycloak returns the authorization token.
6. The application uses the token to request data to the Medusa SaaS Marketplace API about the authenticated user.