November 22, 2023
6 min
Ajibade Adebayo
Founding Engineer @ Rye
It doesn’t need to take weeks to start a new marketplace in your niche anymore.
E-commerce veterans know that the hardest part of starting an online marketplace is finding and onboarding reliable merchants with high quality products. Right behind that is building a platform that sells and scales.
This guide will walk you through building a MedusaJS open-source marketplace, filling it with Amazon products, and earning a margin for each sale. No brand partnerships or inventory needed.
An API to start selling any product
We built the marketplace on Medusa JS, an open-source Shopify. It enables composable, headless, and hyper-customizable eCommerce through community architecture. MedusaJS consists of 3 parts: the backend, the admin panel, and the storefront.
💡
We then plugged in Rye’s Sell Anything API to populate our marketplace with products to sell, as well as set up payment gateway. Rye enables developers to fetch product data from any Amazon or Shopify store, with the mechanisms to automatically send orders back to the merchant to fulfill.
💡
Rye is a set of APIs that enable developers to sync product data and automate ordering. Rye also supports payments via Rye Pay and post-sale management (incl. tracking updates, order cancellations etc.). View docs here.
Piecing the two together into a marketplace
We pieced these 2 together to build a marketplace. Follow these 4 steps to start selling and earning in one day:
The backend
Setup Medusa locally
Add products to the store using Rye’s API
The frontend
Integrate payments using Rye Pay
Place a real order
Note: This tutorial assumes basic knowledge of Git, Node, Bash, and Typescript. We also assume this is run on a Mac or Unix system
Set up your environment
First we need to make sure we have all the prerequisites:
Create an account at the Rye console
Install Postgresql (used for your local database)
Once installed, open
pgAdmin 4. It comes with the MacOS install. Open the app by searching withCommand + Space. Take note of your password, we will need it later.Create your database. Select
DatabasesunderServersin the left panel. Then in the top menu select Object→Create→Database…A modal should popup. Name the database
rye-storeand click save.
Ensure you have Node installed by running
node --version. If you don’t have node:Install node.js with nvm (node requirement ≥18.17.0)
Git
1. Set up Medusa locally
We will first run through steps to set up Medusa.
For the tutorial we will clone two repos that contain default settings. Run the following commands from your terminal to download the code.
Rye Medusa Storefront (NextJS App)
NextJS is a popular frontend framework that Medusa uses to build the frontend.
After cloning the repos, we will create environment variable files at the root of both repos.
Environment files
rye-medusa
Create a file called
rye-medusa/.env
Replace
POSTGRES_PASSWORDwith the password from the Postgres installationReplace
AUTH_TOKENwith the value from console.rye.com/account > Rye API Authentication > API Key Headers
rye-medusa-storefront
Create the environment file
rye-medusa-storefront/.env.local
Once again, replace
AUTH_HEADERwith the value from console.rye.com/account > Rye API Authentication > API Key HeadersReplace
AUTH_TOKENwith the token value inAUTH_HEADERfrom console.rye.com/account > Rye API Authentication > API Key Headers
Install dependencies
Returning back to your terminal, let’s install dependencies and start our backend and storefront app.
Install the dependencies for both repos by running:
Dummy data
Before running the backend we need to fill it with dummy data by running the command below in rye-medusa directory
Starting up
Start both repos locally by running the below command in BOTH rye-medusa and rye-medusa-storefront
Start both repos locally by running the below in both the repos:
Everything will now be running at these three urls:
http://localhost:7001 - Admin page
http://localhost:8000 - Storefront
http://localhost:9000 - Backend api
Lets login to the admin page and view the products page at http://localhost:7001
The username and password for the admin page is
username:
admin@medusa-test.compassword:
supersecret
Once you log in navigate to Products page. It is probably empty but we will fill it up in the next section.
2. Add products to the store using Rye’s API
Now that we have the store up and running locally, lets add some products!
Understanding the Add product endpoint
The Rye’s Sell Anything API allows you to retrieve product data from Amazon or Shopify product by its URL, and list it on your marketplace. Our medusa app comes equipped with a backend endpoint that when called, adds a given product URL to the medusa store. Let’s dissect that endpoint first.
Open up rye-medusa/src/api/admin/rye/products/add-products/route.ts
In order to add products to our store, we first retrieve products from Rye API
snippet taken from rye-medusa/src/api/admin/rye/clients.ts:L21-L52
Once we have grabbed all the products from Rye API, we add them to our store.
snippet taken from rye-medusa/src/api/admin/rye/clients.ts:L60
Calling the Add product endpoint
Now that we understand how the endpoint for adding products was created, lets add products to our store by calling this endpoint!
First we need to grab our access token so that we can make requests to medusa admin endpoints. You can do that by using the curl utility to make HTTP requests.
This will return an access token that we will use to call our /add-products endpoint. Copy the access token value.
response from /admin/auth/token request
Once we have our access token, we can call the /add-products endpoint. Replace the ${ACCESS_TOKEN} with the one we copied above. Run the curl command to add products to the store.
Open http://localhost:7001/a/products?offset=0&limit=15 to check the product page. If everything worked, there should be products in the list! 🎉🎉🎉
To view the added products, you can also head to http://localhost:8000/store
Add margins to earn from each sale
You can make a profit on the products you add by adding a margin. First set the margin in https://console.rye.com/account
Then you can call the add-product endpoint passing margin in the body. This will make sure the price in your store reflects the margin price you will charge customers who buy products you add with Rye.
3. Storefront and payment
Now that we have products, let’s integrate Rye in our storefront to process payments and handle order placement.
Navigate to http://localhost:8000.
Medusa can handle cart creation and checkout flows. To check out and submit the cart, we have to set up a payment method. Medusa supports Stripe or PayPal. Instead of fumbling with additional APIs, we can stick with Rye’s API to process payment.
Now lets look at how this store uses Rye API to integrate:
Payment inputs
Order placement
Understanding the RyePay Integration
First, we have to create the payment inputs using our RyePay package. RyePay handles payment processing by vaulting user credit card details for further transactions.
The code below is part of the RyePayProvider provider to manage RyePay.
The provider will return some values that will be used in later components. Specifically, we will need initRyePayElements and submit.
snippet taken from /rye-medusa-storefront/src/lib/context/ryepay-context.tsx
The initRyePayElements function loads the RyePay package and injects payment inputs into the component. This step would be familiar if you have worked with the Stripe SDK, Spreedly, or Very Good Security. To learn more, check out the Rye Docs.
snippet taken from rye-medusa-storefront/src/modules/checkout/components/payment-rye.tsx
4. Place an Order!
To create a cart in Rye, we need to input the cart data from MedusaJS.
Our storefront code is just a NextJS app so we leveraged NextJS server side to create an endpoint for creating a cart. We have an endpoint, /api/rye/carts/create, that can be used to create a cart. You can check out the implementation at rye-medusa-storefront/src/app/api/rye/carts/route.ts
To call the endpoint above, we created a utility function for creating a cart in rye-medusa-storefront/src/lib/data/index/ts
function in /rye-medusa-storefront/src/lib/data/index.ts
We use this function in the RyePayProvider's createCart function to create or update our Rye cart. Then the submit function places an order via RyePay.
snippet taken from /rye-medusa-storefront/src/lib/context/ryepay-context.tsx
We call the useRyePay hook to get the functions and call them when our checkout button is clicked.
snippet taken from /rye-medusa-storefront/src/modules/checkout/components/payment-button/index.tsx
Placing a real order
With everything assembled, we can now place real orders on our store. Let’s try it out!
Head to Hydrating mist product page
Add the item to cart
Fill in the information and checkout
Once you checkout, you should see the following on the Medusa admin dashboard.
Medusa Admin
Your orders are also visible on the Rye Console.
RyeConsole
Hooray! We placed a real order!