Dittofi
Search
K

Headless Online Marketplace Template

Getting started with Dittofi's Headless Online Marketplace Template

Introduction

In this article, I will show you how you can quickly build an online marketplace with the Dittofi Online Marketplace Template. An online marketplace is a website or app where people can buy and sell things online. Think of eBay or Amazon, where you can buy all sorts of products, or Airbnb, where you can book accommodations, or Uber for arranging rides. eBay focuses on physical goods, while Airbnb offers services like finding a place to stay, and Uber connects riders with drivers for transportation. These platforms, although distinct, share many essential features such as a dedicated space for sellers to list their products or services, a robust system for managing transactions, a direct messaging platform for user communication, and a review process, to name just a few. Understanding and implementing these features can be complex. The Dittofi Online Marketplace Template simplifies this process by providing all the necessary marketplace functionality, pre-built and fully customizable. It addresses both technical challenges and business requirements, helping you get up and running faster. Let's get started!

Step 1: Install the template

If you don’t have an account, visit Dittofi and click on the 'Login' button located in the top right corner.
After logging in, you'll be directed to the dashboard. Click on "Add an App".
On the following page, choose to start with a template. Select the "Dittofi Online Marketplace Template", give your app a name, and then click "Install".

Step 2: Setup Your Template

In Dittofi, the backend actions are where your app's operations are managed. For technical users, think of them as your app's internal API. For non-technical users, this is where you set the rules for how your app works. Find these actions on the third tab and select "Marketplace Create."
These actions perform specific tasks to run your app. This one creates your marketplace and sets up an admin user. To start, click "Run Action" and fill in:
  • Email: [the email of the admin user, for this walkthrough use: [email protected]]
  • Password: [the email of the admin user, for this walkthrough use: pass123]
  • Name: [choose a name for your marketplace, for this walkthrough use: Marketplace]
  • Description: [choose a description for your marketplace, for this walkthrough use: Marketplace]
  • Currency: [select the desired currency, for this walkthrough use: USD]
Click "Run." You should see a 200 success code in the "Response OK" box if everything is set up correctly. Finally, click the back button in the top left to exit the action.
In the actions tab, you'll see different actions sorted by their functions. For example, search for “Listings” to find actions related to managing listings, or “Transactions” to find actions related to handling transactions.
Now search for the action named "Marketplace Show" and run it. This action will give you information about the marketplace you just set up. Next, run "Current User Show." It will provide data about the user you're logged in as, which should be the one you created earlier.

Step 3: Add your first listing

Listings are crucial for any marketplace. They represent the products or services you're offering. Let's add your first listing.
Go back to the actions page and search for "Own Listings Create". This action allows you to create a listing. Run the action and enter:
  • Name: [Name of the product, for this walkthrough use: Product 1]
  • Price: [Price of the product, for this walkthrough use: 300]
  • Description: [Description of the product, for this walkthrough use: Product 1]
Afterward, go back from the action and find "Listings Query". This action lets you search for listings on the platform. Run it, and you should see a list of the listings you created earlier.

Step 4: Introducing the database

On the second tab of Dittofi, you'll find a section dedicated to the database setup. This is where you can view all the tables that store your app's data. Click on the second tab to access the database setup. Here, you'll see a list of tables that organise your app's information.
Now, take a closer look at the data generated by your actions. Navigate to the "Users", "Listings", and "Marketplace" tables to see the information that was created when you ran your actions earlier. Note you can use the hamburger icon in the top left to search for these tables by name.

Step 5 - Managing User Accounts

Marketplaces consist of two types of users: customers and providers. A customer is someone who buys products or services, while a provider is someone who offers and sells them. In most online marketplaces, users can act as both customers and providers; for instance, on eBay, you have the ability to both buy and sell items. Finally, a marketplace may have platform admins who oversee and manage the operations of the entire platform.
Go back to the actions page and search for "Current User Create". This action will create a new user and automatically login that new user. Run the action and enter:
  • Email: [Email of the user, for this walkthrough use: [email protected]]
  • Password: [Password of the new user, for this walkthrough use: pass123]
  • Confirm Password: [Password of the new user, for this walkthrough use: pass123]
Next, run "Current User Show." It will provide data about the user you're logged in as, which should be the one you just created.
To log back in as the previous user you created when setting up the marketplace you can run the action “Authentication Login” with:
  • Email: [Email of the user you want to login with, should be [email protected]]
  • Password: [Password of the user you want to login with, should be pass123]
Now, take some time to try “Authentication Login” and “Current User Show” to demonstrate how you can switch between users in your marketplace. To finish, ensure you are logged in as the user you created in Step 2: Setup Your Template. This user is a system admin and you will need them for the next step of setting up your payment gateway.

Step 6 - Configuring your payment gateway

Before we can proceed with our test transaction, we need to set up a payment gateway. Think of this as the online equivalent of a card machine you'd use in a physical store. In our case, we'll be using Stripe as our payment gateway provider.
Go to www.stripe.com and click on "Sign in".
Now that you have logged in to Stripe, the dashboard opens. In the left menu, first click on "Developers" and then on "API keys".
Once you have clicked on "API keys", the page with the API keys opens. Under Standard Keys you will see the Publishable Key and above the Secret Key there is a button "Reveal live key token". Now click on it to display the secret key.
To switch Stripe to the Sandbox (Test Payments) mode or Live (Real Payments) mode, click on "View test data" in the left menu. Note that Sandbox and Live Mode have different keys. For now take the test secret key (starting sk_test) and copy it to clipboard.
Now head back to your Dittofi app and run the action Marketplace Update with:
  • secret_key: [Secret key you just took from Stripe]
You should see a 200 success code in the "Response OK" box if everything is set up correctly.

Step 7 - Your first transaction

A transaction encompasses the entire interaction between a buyer and seller. Think of a transaction as the entire journey from selecting an item in a physical store, engaging with the salesperson, completing the purchase, arranging for delivery, to finally providing feedback on your experience.
The first step in a transaction is for the customer to request to purchase a particular product or service. This is analogous to a customer taking a product to a checkout in a physical store. To begin this process in Dittofi go to the click on the second tab to access the database setup and open the listings table. Here you will see the listings you created earlier. There is a column called “id”. Make a note of the “id” of a listing you want to test your transaction with:
Now go back to the actions tab and run the login action with the email and password you used for your second user. This is important to ensure you are logged in now as the customer rather than an admin. As explained in Step 5 - Managing Your Accounts, you can run Current User Show to check the user you are logged in as. Once you are sure you are logged in as the second user go and run the action Transaction Initiate with:
  • listing_id: [the id of the listing you took from the listings table a moment ago]
  • start_time: (optional field) [if users will be renting your product over multiple days, specify the start time for the rental, otherwise leave blank]
  • end_time: (optional field) [if users will be renting your product over multiple days, specify the end time for the rental, otherwise leave blank]
If everything went well you should see a 200 success code in the "Response OK" box and in the Body you should see a url like this: { Data: “https://…” }. Copy just the url and go to another tab in your browser and paste the url and hit enter. This should take you to a checkout screen where you should complete the purchase. If you used your test stripe secret key earlier then at this point you can enter 4242 4242 4242 4242 as the card number to test the transaction.
Congratulations, you successfully created your first transaction! Now, in Dittofi go to the click on the second tab to access the database setup and open the transactions table. You should see a record here with the same listing_id that you entered in when running the action.

Step 8 - Accept, Cancel or Decline Transactions

When booking a hotel room, the money isn't normally transferred until you arrive at the destination. Similarly, in an online marketplace, initiating a transaction doesn't immediately transfer the money. Instead, it initiates a review process where the seller can choose to accept or decline the transaction. There's a specific timeframe allocated for this decision; otherwise, the transaction may expire. Additionally, customers have the option to cancel orders, which can lead to either a full or partial refund.
Transactions are said to move through different “states”. For example, in the marketplace template, transactions progress through the following states:
  • Initial: The customer has initiated a transaction and navigated to the checkout page but has not yet provided payment details.
  • Preauthorized: The customer has provided payment details, and the payment has been authorised on their account. However, the money has not yet been transferred.
  • Accepted: The seller has accepted the transaction, and the funds have been earmarked in the seller's online account.
  • Cancelled: The customer has cancelled the transaction, and a refund will be issued.
  • Delivered: The transaction has been successfully completed, and the funds are in the process of being transferred to the seller's actual bank account.
It's important to note that this represents the default setup, and it's customizable. Different marketplaces may have varying workflows, and adjustments may be needed to tailor the transaction flow accordingly.
The majority of the complexity in building an online marketplace comes in managing the states of different transactions. There are specific rules dictating the transitions between these states. For instance, once a transaction is cancelled, it cannot subsequently be accepted. To check the current state of a transaction, refer to the 'transaction_state_id' column in the transactions table. This column corresponds to the 'id' column in the 'transaction_states' table. Take a moment to familiarise yourself with these states. Importantly, it's advised not to manually modify the database to change states. Instead, employ actions provided by the platform. Changing from one state to another may trigger additional actions, such as processing payments, which are managed within these actions.
Now go to the actions tab and filter in the descriptions column for Transactions. Here, you'll find various actions designed to manage different stages of a transaction:
  • Transactions Booking Accept: This action is utilised by the provider of a service to transition a transaction from the preauthorized state to an accepted state. As a result, the funds that were preauthorized from the buyer will be transferred into the seller's account.
  • Transactions Booking Cancel: This action is initiated by the buyer of a service. It's used to move a transaction from either a preauthorized or accepted state to a cancelled state. In addition to this, any funds involved will be refunded back to the buyer.
  • Transaction Booking Decline: The provider of a service uses this action to move a transaction from the preauthorized state to a declined state. This action also initiates a refund process, returning any money to the buyer.
  • Transaction Deliver: This action is employed to mark the transaction as “delivered”. This action concludes the process by transferring the funds to the seller.
Now, click into the Transactions Booking Accept action and run the action with:
  • Id: [the id of the transaction - you can find this by looking in the id column of the transactions table on the database tab]
Once completed, the transaction will transition into an 'accepted' state. To verify this, inspect the "transaction_state_id" column in the transactions table. Note, similarly, you could have used the "Transaction Booking Decline" or "Transaction Booking Cancel" actions with the same ID to move the transaction into the 'declined' or 'cancelled' state, respectively. However, for the purpose of this walkthrough, you should just use the Transactions Booking Accept action for now and leave the action in the accepted state.

Step 9 - Messages

In online marketplaces, buyers and sellers engage in post-transaction communication through a dedicated chat feature. This platform focuses on the specific transaction at hand, enabling users to iron out details. For instance, on Airbnb, you may inquire about check-in procedures, while on Uber, it's the channel to communicate with your driver. Similarly, on platforms like Amazon and eBay, this feature allows users to discuss shipping options, address any concerns, and provide feedback on the transaction.
To create a message, navigate to the 'Actions' tab and search for 'Messages Create'. Click and run the transaction with the following parameters:
  • transaction_id: [the id of the transaction - you can find this by looking in the id column of the transactions table on the database tab]
  • content: [the message you wish to send]
You can send messages as either the buyer or seller of the transaction. To view the messages, navigate to the 'Messages Query' action and execute it with the following parameter:
  • Transaction_id: [Insert the ID of the transaction. You can find this by referring to the 'id' column in the transactions table on the 'Database' tab]."
You can also go to the database tab and look in the messages table to see all the messages in your marketplace.

Step 10 - Deliver Transaction and Leave Reviews

Congratulations on reaching Step 10! You've successfully set up your marketplace, initiated a test transaction, and started a conversation around it. Now, it's time to mark the transaction as delivered, ensuring the seller receives their payment. Additionally, both buyers and sellers can review the transaction to provide feedback and build trust and credibility within your marketplace.
To mark the transaction as delivered you can run the action Transactions Deliver with:
  • Transaction_id: [Insert the ID of the transaction. You can find this by referring to the 'id' column in the transactions table on the 'Database' tab].
This will update the transaction_state_id and trigger a payout to the seller.
To leave reviews, you can use the following actions:
  • Transaction Reviews Create Customer: Use this to create a customer review. Ensure you're logged in as the customer before proceeding.
  • Transaction Reviews Create Provider: This action allows you to create a seller review. Make sure you're logged in as the provider to submit the review.
Both actions use the following parameters:
  • id: [Insert the ID of the transaction. You can find this by referring to the 'id' column in the transactions table on the 'Database' tab].
  • Content: [Provide the content of the review].
  • Rating: [Assign a numerical rating to the transaction].
You can check the database tab and look in the reviews table to see all reviews left in your marketplace.