Homepage

Get Started with the pOS Marketplace Template

Last edit: Dec 12, 2023

The pOS Marketplace Template is a fully functional marketplace built on platformOS with features like user onboarding, ad listings and ads, purchase and checkout process, and online payment. Following the tutorial, you can deploy this code within minutes to have a list of working features and start customizing the back- and front-end code.

Screenshot of the demo project marketplace

Preview

You can preview the marketplace template at our demo site here: getmarketplace.platformos.dev

Note

If you are going through the process of installing your marketplace on the platformOS Partner Portal, you will notice that some steps are slightly different than the ones described in this Get Started guide. This is because on the Partner Portal we automatically deploy your site to a new instance, while when you follow this guide, you do all steps manually.

Prerequisite: Register on the Partner Portal

Important

You might already have access to the Partner Portal if a registered Partner created an account for you. If you already have a Partner Portal account, please skip this step.

The Partner Portal is an online interface, where you can create, manage and configure your sites (called Instances), and create and manage the permissions of other users (called Partners).

To register on the Partner Portal, go to https://partners.platformos.com/accounts/sign_up, use your GitHub or Google account, or fill in the form:

Field Description Example
First Name Your first name John
Last Name Your last name Smith
Email Your email address john.smith@example.com
Password Your password should consist of at least six characters that are a combination of uppercase and lowercase letters, numbers and symbols. Uk9bpBMJ6s

Once registered, you will get an email verification. Click on the Accept verification link to activate your account.

Step 1: Install the pos-cli

The pos-cli is a command line interface that helps you deploy configuration files and assets to your platformOS site.


Important

You will need a recent version of NPM (Node Package Manager) installed on your computer to install the pos-cli. NPM is distributed with Node.js, which means that by installing Node.js, you automatically get NPM installed on your computer. If you haven't installed Node.js yet, follow this tutorial to install it.

Once you have Node.js installed, start your command-line tool (for example, Terminal on a Mac, or Git Bash on Windows), and enter:


npm install -g @platformos/pos-cli

If your Node.js is installed for all users you might need to use sudo to install npm packages globally:


sudo npm install -g @platformos/pos-cli

Use the following command to test the pos-cli:


pos-cli -v

If the pos-cli has been installed correctly, running this command displays the version of your pos-cli. If the pos-cli hasn't been installed, running this command gives a command not found error.

Step 2: Create Instance

To be able to deploy your site, you have to create an Instance on the Partner Portal. Instances have a URL, and they represent different development environments, like staging or production. We recommend creating a staging environment for going through the steps in this tutorial.

On the Partner Portal, in the menu on the left under Create, select Instance, and fill in the form:

Field Description Example
Name The name of your Instance mymarketplace
Tags Enter up to 5 tags (optional). You can use tags to group your Instances, for example by project or client. marketplace, test
Partner Select the Partner the Instance will belong to. MarketplacePartner
Data Center Select an endpoint (staging or production). STAGING

Select the Staging/Unbilled Billing Plan that appears, and click on the Create button. We create the Instance, and once it's done (in a couple of minutes at most), send you an email with a link to your Instance and other useful information.

Step 3: Add Instance to pos-cli

Note

Make sure you remember your Partner Portal account email and password — you will need them to authenticate your environments. If you logged in using Google or Github, go to the Instance details view in Partner Portal where you will find the pos-cli command ready for copy and paste. It shows all the parameters you need, so in this case, you won't need to remember your password.

On your local environment create a new directory and change to it. This is where you will put the codebase for your marketplace.


mkdir marketplace
cd marketplace

Add your Instance to the pos-cli. This will ensure that you can use the pos-cli to download your codebase, and sync or deploy to the Instance.

Use the pos-cli env add command and authenticate with your Partner Portal credentials.

Tip

You can copy this command pre-filled with your Instance URL from your Instance page on the Partner Portal.


pos-cli env add [YOUR_ENV_NAME] --url [YOUR_INSTANCE_URL]

For example:


pos-cli env add staging --url https://mymarketplace.staging.oregon.platform-os.com

A message "Environment [your Instance URL] as staging has been added successfully." is displayed.

Step 4: Clone the repository

If you need to create a new project, you can initialize the directory structure using the pos-cli init command. You can either initialize platformOS core or download the directory structure from a given git repository and extract it in your current directory.

Create your codebase by cloning our marketplace GitHub repository.


pos-cli init --url https://github.com/mdyd-dev/product-marketplace-template.git

Step 5: Build assets

Install the marketplace package and any packages that it depends on then build it using npm commands.


npm install
npm run build

Step 6: Deploy

To be able to display your marketplace on your site, you have to deploy your codebase using the pos-cli deploy command.


pos-cli deploy [YOUR_ENV_NAME]

For example:


pos-cli deploy staging

A progress indicator shows that the deployment is in progress, and once it finishes, a "Deploy succeeded after [time]" is displayed.

Go to your Instance URL to explore the marketplace you just deployed. If you already had the Instance URL open in your browser, refresh to display the changes.

Step 7: Set up your marketplace

To access the admin panel of your marketplace:

  1. Click on Log in, then on the Register link in the text "Don't have an account? Register".
  2. Register a user with this email address: admin@example.com. You can enter any password.
  3. Enter the Admin section from the main menu.
  4. Go to the Marketplace Setup section.

To set up Stripe integration:

  1. Go to https://stripe.com and register your Stripe Connect account.
  2. Copy and add the redirect URI in your Stripe Connect settings under Integration/Redirects:
    [YOUR_INSTANCE_URL]/payments/account/success, for example: https://mymarketplace.staging.oregon.platform-os.com/payments/account/success. You can find this link on your Dashboard on the Setup page.
  3. Enter your Stripe public key, secret key, and Stripe Connect account client ID.
    • Marketplace Owner Fee (percent): The fee that the seller pays for selling through the marketplace. For example, if the product costs 50$, the buyer pays 50$, then the seller gets 50$ minus the marketplace fee. In this example, if the marketplace fee is set to 10 (percent), then the seller will get 45$. The marketplace owner would get 5$ but as a default, the marketplace owner pays the fees for using Stripe Connect, so they will get 5$ minus Stripe's fee.
    • Stripe Publishable Key: find under Developers/API keys
    • Stripe Secret Key: find under Developers/API keys
    • Stripe Owner Connect account client ID: find under Integration

Questions?

We are always happy to help with any questions you may have.

contact us