Headless describes the technology architecture of marketplaces built on the Sharetribe developer platform. Headless software means that the frontend and backend portions are hosted separately. When a marketplace is customized with code, the backend is hosted and managed by Sharetribe, while the front end is hosted and managed by you. The frontend and backend interplay through APIs; the frontend “calls” the backend, prompting the backend to process the request and respond.
​

Building a headless marketplace lets you create custom marketplaces faster than building one from scratch. Developers build a custom frontend, using the pre-built backend functionalities from APIs.

The front end refers to the marketplace website or mobile application. In a headless architecture, this portion is built and hosted separately from the marketplace backend. Frontend applications can also be referred to as client applications.

The Sharetribe Web Template is the most common way to build a marketplace frontend with Sharetribe. You may build your frontend completely from scratch too.

The marketplace front end communicates with the backend via Sharetribe APIs. It sends and retrieves data through these APIs. For example, client applications rely on the Asset API to retrieve content created through Pages, such as a landing page.

The backend refers to the marketplace database and supporting infrastructure. In all cases, the backend is hosted, maintained, scaled, and secured by Sharetribe. It provides tools like API resources, extended data, or the transaction process engine to developers that make building a custom frontend application much faster and easier.

Custom-coded frontend applications (or marketplace applications) store, retrieve, alter, and use data in the backend via Sharetribe APIs.

Sharetribe APIs are the interfaces through which marketplace application(s) communicate with their Sharetribe-hosted backend. Though distinct from the backend, APIs and backend are often used interchangeably.

Sharetribe has four major types of APIs. Each of these four APIs has several API endpoints. Each endpoint represents a tool or functionality that the developer can use when building and powering your marketplace application.

The endpoints available represent what Sharetribe can do and how it can do it. Because the Sharetribe developer platform is a tool for building marketplaces, the available endpoints are designed specifically to support marketplace use cases. Endpoints are grouped under resources, or data entities, that they impact.

An API resource refers to a predefined data entity available through Sharetribe APIs. The most important resources in Sharetribe technical are User, Listing, Transaction, and Assets. User, Listing, and Transaction resources represent a functional grouping of marketplace building blocks developers use to save time creating a marketplace application. For example, the Listing resource includes availability calendar features, which can be used to create custom booking and reservation experiences.

You can learn more about the User resource here, the Listing resource here, and the Transaction resource here. You can learn more about Assets here.

Events log changes to an API resource. If a new resource is created or an existing resource is modified, an Event occurs. Events thus provide a history of actions in your marketplace. They are also a mechanism for initiating actions in other software due to something happening in your marketplace. Sharetribe has an integration with Zapier, which can make building further integrations into many other software applications easier.

Sharetribe Web Template is the best way to start building a marketplace customized with code. The Template is an open-sourced website application modifiable with coding. Using it allows building a custom marketplace at a fraction of the cost or time required to build it from scratch.

Many settings are configurable in Console. These include the listing type, search page layout, search page fields, listing fields, and many more. Launching a custom code marketplace with the template requires a developer.

Environments describe different instances of a Sharetribe account backend. There are three environment types: a Test environment, a Development (Dev) environment, and a Live environment. Test and Dev are included with every Sharetribe account.

Test environments are for building features and content into your marketplace using no-code tools in Console. One example of how to use the Test environment would be to create or edit your content pages. You might create a new content page in Test, see how it looks on your test marketplace, and then "Copy to live" the page when it is ready.

The Development environment is used to build and extend your custom marketplace by developers. You may add your own test Stripe account to the development environment and use it with code to build custom features you will later deploy to your live site.

A Live environment is needed to launch a marketplace. It lets your marketplace sign up real users and process real transactions.

Once live, we recommend using your environments and associated apps (front ends) in this way:

Extended data lets developers modify the backend to store custom information. Specifically, the feature allows for changing what data the User, Listing, and Transaction resources store. By capturing custom variables or IDs to these pre-built resources, developers may support a broad range of use cases using a turnkey set of backend tools.

Click here to learn more about the different use cases supported by extended data.

The transaction process defines the rules of what and how transactions happen in the marketplace. Anytime two users interact on a Sharetribe marketplace; the transaction process determines what steps are available to them. When they are available, and what happens due to these steps. The transaction process editor is the tool to modify and customize the transaction process

You can have different transaction processes and different versions of the same transaction process to use and experiment with different ways of transacting, like renting and buying products, in the same marketplace. Some transaction processes are defined by default and are set by your Listing types' no-code settings. You can see the transaction processes of your marketplace in Console's “Advanced” section.

Click here to learn more about transaction processes and for tips on how to design your own.

Assets as a concept refers to the API resource that stores your text, visual content, and no-code settings. Your landing page texts and pictures, your Terms page legalese, your marketplace texts, your listing layout settings, and branding are all stored in the Sharetribe backend as part of the Asset tree.

Your marketplace frontend retrieves Assets from the backend and renders them per your marketplace's design and settings. Assets are created in Console without code. For further, more technical information about Assets, consult this article.

Content pages only feature content created by you, the marketplace operator. Landing pages, “About” pages, and FAQ pages are examples of content pages. Content pages can be built and edited using Pages.

Dynamic pages feature content created by your users. The search page displaying listings is a dynamic page. Often, dynamic pages offer users the ability to interact with them, such as when customers are selecting the length of a booking from a listing or entering their payment information into the checkout page.

Marketplace texts include short written texts scattered around a dynamic page’s interface; button labels, error messages, and help texts are all examples. They are textual, brief (a sentence or two), and highly contextual.

You can modify your marketplace’s texts using the Marketplace texts editor in Console.

Pages is a feature used to create and edit content pages in Console. In Pages, operators create content by defining one or more Sections. Each Section comprises Blocks, or subsections, laid out according to the Section template. Depending on which kinds of Sections and Blocks you choose for your page, you can create a wide range of content.

Pages include 4 default content pages: the About page, the Landing page, the Privacy policy page, and the Terms of Use page. These can be edited but not deleted. Operators may create any number of custom content pages besides the default pages. You can read more about using the Pages feature here.

Users are one of the API resources available. Users are created when anyone registers to your marketplace. Account information like signup date, email, and password are stored in the User resources. Custom data can be stored in the User resource using extended data.

Users let you control access to certain marketplace functionalities. Moreover, User accounts may be in different states, such as pending verification, banned, or deleted.

User's extended data is how you store custom attributes to the User resource. Sharetribe requires you to define an email and password for every User account created. Sometimes, a marketplace will need to collect more info like a phone number or business ID; User extended data stores this custom information.

Moreover, User extended data can store information about the user’s role, level, or permissions and define actions that can be taken in the marketplace based on this data.

Sharetribe has two possible roles for a registered user: customer and provider. Unless specified otherwise by your application, all users can be both customers and providers by default. This means that even if a person has created a listing, which means they can be a provider, they can also be a customer of someone else's listing. The role only applies to their function in a transaction.
​

Extended data can be used to limit users to only customer or provider capabilities.

Sharetribe includes one more user type: the marketplace Operator. This is the admin user. They are not a user in the marketplace – they cannot sign in to the marketplace with the same credentials they use to sign in to Console. The Operator can, however, take actions on the marketplace through Console or through the Integration API, when those actions are defined for the operator. Operators cannot communicate between customer and provider within the transaction.

Listings are one of the API resources available. Listings are used anytime you need one side of the marketplace to create and add information that the other side of the marketplace finds and interacts with.

Listings can represent items for purchase, services for rent, storefronts for viewing, and much more. In more complex marketplaces, you may have multiple types of listings; reverse marketplaces have one listing type to put forth customer requests and another to capture bids or proposals by providers.

Listing extended data is how you store custom attributes to the listing resource. Fields that your user fills out while creating their listing, such as the listing category, are one use case for extended data. These fields can become search parameters like a single select filter or a keyword search for customers.

Other use cases include using listing extended data to capture listing classification, facilitate integrations, or modify sorting behavior. Ultimately, listing extended data lets developers create listings that look and function exactly how you need at a fraction of the effort of building such features from scratch.

A listing state defines where a listing is in its lifecycle. Listings that are in progress, but not published are in "draft" state. Listings waiting for approval (if this feature is turned on) are in "pending approval" state. Active listings are in "published" state; only listings in "published" state are searchable and can be used to start a transaction. Closed listings are in "closed" state. Operators or listing authors can close a listing. Finally, "deleted" state refers to listings whose data has been completely removed.

Marketplaces can require all listings to be approved before they are published on the marketplace. A listing that is pending approval is visible only to its author and the marketplace operator through Console, but is not discoverable by any public API endpoints. Marketplace operators can review and approve listings from Console, though a custom interface may be built to review and approve listings as well.

Search refers to the discovery process undertaken by the demand side when looking for supply. In Sharetribe, search is built around listings. A Sharetribe marketplace can return listings based on parameters the customer inputs using various techniques, such as keyword search, location search, or filtering selections. Search results are sorted by creation date, with more recent listings coming first, or by custom attributes stored in listing extended data.

Listings often take a price. Typically, providers set the price of their listing using pricing units set by the marketplace. Rental marketplaces might ask providers to price by the rental time unit, like hours, days, or months, for example.

Stock is the number of available units of a listing. Your marketplace can allow or disallow customer behavior based on the stock quantity. For example, if a listing does not have available stock, it cannot be purchased by the customer.

Stock is typically set by the provider when creating their product listing. Transactions adjust stock amounts. If 2 units of a listing are sold, the listing’s stock count decreases by 2.

Availability calendars define when someone can and cannot book times from a calendar. It is an often-used feature in service or rental marketplaces. Availability is added by the listing author when creating their listings and editable thereafter. Customers can select times from the available calendar. Whether customers book days, nights, 30 minutes, half-days, months, or some other measure is up to you; Sharetribe's developer platform understands booking increments as small as 5 minutes.

Syncing information between an availability calendar in Sharetribe and a 3rd party calendar service is possible with a lot of custom development. The extent of the work required depends on your needs and the calendar. Don't hesitate to get in touch with our support team at hello@sharetribe.com if you have questions about building such a feature.

Seats let providers define how many spaces there are for an available time. This is taken into account during the booking process. Customers cannot reserve more than an available number of seats. Conversely, customers can reserve the same times others have reserved if there are available seats. For example, marketplaces selling tickets to events can use seats to let providers define how many tickets are available and let customers buy in confidence that there are enough seats available.

Transactions are one of the API resources. Transactions are used anytime two users are interacting on the marketplace. How they interact–the possibilities available to them throughout their interaction–is determined by the transaction process. You may have multiple different types of transaction processes and thus different types of transactions. For instance, you could have rental-style transactions, which include booking possibilities in the transaction process, and e-commerce-style transactions, with instant payment and stock management possibilities in the transaction process, in the same marketplace.

The transaction process defines the rules of what and how transactions happen in the marketplace. Anytime two users interact on a marketplace, what steps are available to them, when they are available, and what happens as a result of these steps is enclosed in the transaction process. You can have different transaction processes for different ways of transacting, like renting and buying products, in the same marketplace. You can see the transaction processes of your marketplace in Console’s “Advanced” section.

Click here to learn more about transaction processes and for tips on how to design your own.

Transactions may include messages. For a message to be sent, a transaction resource must be created. They can be available at any point in the transaction to both the customer and the provider. Operators can view any message in Console within their Manage Transactions page.

Marketplaces can send custom email notifications during transactions. What your email says and how it behaves is controlled by your transaction process. Sharetribe’s default transaction processes include template notification emails, such as a receipt or reminder to leave a review.

You can learn more about transaction email notifications here.

It is possible to send SMS notifications, but this requires a 3rd party integration. You may use Zapier to send such emails or build bespoke integrations into tools like Twilio.

Sharetribe features stock management. Providers can set their available stock while creating and managing their listings. During a transaction, stock amounts are modified based on what happens. If a customer requests to buy an item, for example, the stock amount can be decremented to reflect this request.

Adjusting stock amounts is handled through the transaction process.

Bookings are time reservations made in a provider’s calendar. After a provider sets their availability in their listing, customers can make bookings. Providers can accept, reject, or propose new times. Booking actions happen during a transaction. A transaction process handles what booking possibilities exist for customers and providers throughout a transaction.

Payments are a typical part of a transaction. Payments may be “on-platform” (through the marketplace) or “off-platform” (made outside the marketplace). Sharetribe marketplaces can facilitate on-platform payments using the built-in payment system or by integrating their own payment system. In addition to charging the payment method, marketplace payments also involve charging a commission, payouts to providers, and refunds. Payment behaviors are controlled by the rules set in your transaction process.
​
You can integrate a third-party payment provider into the transaction process with custom development.

Stripe builds software for online payment processing. Sharetribe comes integrated with Stripe’s Connect tool, which lets customers purchase from providers directly. As part of this, Stripe Connect handles provider onboarding, payment processing, payouts to providers, and commission charging. The Stripe Dashboard gives you a detailed view of every payment.

Reviews can be created by a customer and provider during a transaction. Reviews consist of free text and a 0-5 star rating. Who can leave a review and when reviews can be left is determined by the transaction process.