Understanding Headless eCommerce - Glossary of Terms and Concepts

By Jakub Zbąski

Featured image

Entering the world of headless ecommerce business, you may come across many terms that are new and unfamiliar. Elements such as frontend, backend, framework, or API may seem clear only to technical individuals.

The first step in creating a headless commerce platform is understanding the terminology used in building such a solution. In this post, I will explain the key concepts and topics, making it much easier to overcome the entry barrier into the headless realm. Let's get started!

A Day in the Life of a Programmer

Before we begin discussing topics from the world of headless platform architecture, let's imagine a day in the life of a programmer:

The programmer is tasked with building an ecommerce platform.

Before diving into coding, they face a choice: whether to develop the monolithic ecommerce platform or go with a headless approach.

After selecting the commerce architecture, they are faced with another decision. Which framework should they choose to build the ecommerce solution?

Once the programmer has made a decision regarding the architecture and framework of an ecommerce store, they can proceed with application programming (or coding). In the case of choosing a headless commerce architecture, the programmer needs to create both the backend and frontend layers (you can read about the headless commerce benefits here). These layers need to communicate with each other in some way. Here, we have another choice to make. We can opt for communication through either REST API or GraphQL.

After creating the online ecommerce platform, the programmer faces a choice of how to host the application, which means placing it on a server (a computer connected to the network, operating 24/7) and making it accessible to all internet users by entering the appropriate address in a web browser. They have options such as private VPS or a cloud server. Headless provides more flexibility in choosing the hosting method, and this aspect goes beyond the scope of today's post. We will soon write a dedicated article on our blog about hosting applications in a headless model.

Now that we have discussed what a day in the life of a developer looks like and the topics they encounter on a daily basis, let's delve into the subject of headless commerce and explain what it all means.

Frontend vs Backend

Understanding the separation between the frontend and backend layers is best illustrated with an example:

Let's imagine a gaming console like PlayStation. When we buy a PlayStation, we acquire a device that allows us to play games, store files in its memory, and more.

However, what we connect this console to, depend on us. It can be any TV, monitor, or any other display device. We just need the appropriate cable to connect our PlayStation to the display, and we can start playing our favorite games.

In this example, the role of PlayStation is equivalent to the backend. It holds the necessary logic for executing the store's functionalities and managing data. That is its primary task. It doesn't concern itself with how that data will be presented to the user.

On the other hand, the frontend is the visual layer of the application. It is responsible for displaying data to the user in the best possible way and enabling user interaction with the application (such as navigation, data input, etc.). This allows for modifying the user interface without affecting the logical layer of the application. The separation of the frontend and backend layers enables the implementation of unique user experiences, distinguishing our platform from competitors. It also facilitates the deployment of new omnichannel experiences and enables the use of the application on various devices.

The headless server additionally provides an API layer that grants access to the data and functionalities. Let's imagine this as an HDMI input on the PlayStation console. The API layer is designed optimally for the server, without concerning itself with the specific device that will utilize it. The only requirement is to use the API interfaces according to their specifications. You will learn more about APIs in the following paragraphs of this post.

headless glossary1

Headless vs monolithic architecture

What is headless architecture?

In programming language, headless architecture refers to the separation of the backend from the frontend of an application.

The traditional ecommerce platforms with monolithic approach tightly couples the database, backend, and frontend together. This means that any decision or change in the backend can impact or limit the behavior of the frontend (and vice versa). While this solution was popular during the creation of early ecommerce platforms, it is unable to meet the requirements imposed by the modern eCommerce market due to problematic modification, difficult scalability, and other key factors.

Examples of monolithic, traditional platforms for commerce features WooCommerce, Magento, or PrestaShop. These are commonly chosen solutions for building traditional online stores. The most popular content management platforms based on monolithic architecture are WordPress and Drupal.

The implementation of headless commerce approach removes this coupling. The backend (headless server) focuses solely on processing and handling logic and data. Similarly, the frontend focuses solely on how information is presented to the user taking care of the best customer experience. The frontend can be a website, a mobile application, or a voice assistant such as Alexa. The headless approach is the most commonly used solution when creating modern and large-scale online stores that prioritize platform development.

There are multiple headless solutions out there but the most interesting ones are Medusa.js and Saleor.

What are the advantages of the headless approach?


  • Using headless architecture supports greater independence in creating logic and the API layer. Developers no longer need to build solutions around it as in monolithic approaches.
  • Headless solutions make scaling and integration with external services much easier.
  • Improved security - only the frontend interacts with the backend, which is typically maintained in a different location than the frontend. Users do not have direct access to the backend, which means they cannot independently manipulate the database.


  • The frontend of the application can be built using any technology. It can also be a website, a mobile application, a voice assistant application like Alexa, etc giving great digital experience on multiple channels.
  • Using headless technology allows the frontend developer to fully focus on good design and user experience without being limited by the backend.
  • There are many hosting providers that specialize in maintaining frontend applications, reducing the overall cost of application maintenance and significantly improving their performance.
  • Implementing visual changes does not carry the risk of modifying the part of the application responsible for the logic. This provides greater flexibility for developers, enabling the creation of unique user experiences.
headless glossary2

What is a Framework?

A framework serves as a "skeleton" and provides a set of tools, functions, and various components that facilitate and accelerate the process of building applications. The framework establishes a standard to follow during the development and deployment of a project. It enables the programmer to avoid building everything from scratch, which significantly reduces project implementation time.

Many frameworks are developed under an open-source license. This means that they are built by the community, and their usage is completely free. The advantage of using open-source ecommerce platform frameworks is the ability to consult any issues or doubts with the community that creates the respective solution.

Frameworks are built in various programming languages and, similar to languages, serve multiple purposes. Some frameworks are used for headless storefronts, such as React.js, Next.js, and Vue.js. Others are utilized for back-end ecommerce platform. Examples include Node.js (on which Medusa.js is based) and Django (used to create the Saleor platform). In addition to the above, there are frameworks used for building content management systems and many other solutions. The benefit of using these frameworks is the optimization of project development time - we don't have to reinvent the wheel because all the fundamental and commerce functionality (such as user accounts on the backend or session management on the frontend) are already available.

API - what is it?

API (Application Programming Interface) is a method of communication between the frontend and backend layers of an application. It allows for the connection and exchange of information between these layers. Think of an API as a waiter in a restaurant - they act as the "connection" between you and the chef who prepares your meal. First, they take your order to the kitchen, and once it's ready, they deliver it to your table.

Headless commerce communicates via API which is used to transmit the list of products from the backend (which retrieves it from the database) to the frontend (which displays it in a user-friendly manner), create a shopping cart, place an order, allow the administrator of the headless commerce setup to create a product, and so on.

In the case of headless architecture, the headless API supports integration with external services. Let's imagine that our commerce platform includes a contact form. After a user fills out the form, we use SendGrid to send the form's contents via email to the administrator. When the user clicks the "Send" button, we utilize the SendGrid API, specifically its component responsible for sending emails, providing the form's content (this is a simplified example, as communication with external services should ideally go through our backend for the security of storing authentication keys for external services).

API can also serve as a security gateway. When we want certain data to be accessible only to a specific source (for example, only my frontend can query my backend for a list of products, and no other application can do so), we can send an API key (token) along with the API request, which is then verified on the backend. If the sent key is valid, we return the information. If the key is invalid or absent altogether, we can return a 403 error (access denied to the requested resources).

Another benefit of API is the ability to send different information depending on the frontend querying the backend. Let's imagine we have an online store built with headless technology. We have a backend and two frontends—a website and a mobile application. When we make a request for a list of products from either frontend, we include information about which frontend made the request. If we have such a business requirement, based on this information, our platform offers a different list of products on the mobile application and a different one on the website. This can be useful when implementing new sales channels.


There are two most popular architectures for creating APIs: REST API and GraphQL.

REST API (Representational State Transfer) is a set of principles based on classical HTTP methodologies: retrieving, creating, updating, and deleting data (GET, POST, PUT, DELETE). This means that the API exposes corresponding endpoints (also known as URLs) to which we can make appropriate requests to perform the desired operations. It is a classic and widely adopted approach for building API architectures.

An alternative approach to REST is GraphQL. In this solution, only a single endpoint is exposed, to which a request must be made in the appropriate format to retrieve or send information. When retrieving information, we make a query request, while any operations related to data manipulation (creation or editing) are performed through mutations. Another difference is that during the query creation, we need to define the specific information we want to receive. For example, if we want to query a list of products in our headless commerce setup, we need to specify that we want to receive the product's name, price, and main image (if those are the only pieces of information we want to display for each product on the list). This results in a smaller payload, compared to REST, and ensures that we always receive the exact data we need (in REST, if we are missing some information in the response, we would have to make additional requests to other endpoints to obtain that information). These benefits can be crucial when aiming for low energy consumption and reduced data transmission on the frontend (such as when developing an application for Apple Watch). GraphQL is a relatively new solution, but it is quickly gaining a strong following and being implemented in an increasing number of projects.

Which solution to choose? There is no definitive answer to this question. If your headless commerce setup requires minimizing the amount of data transmitted over the internet (for example, the application will operate in countries where mobile internet is expensive) or needs to conserve energy (for small mobile devices like smartwatches), then GraphQL may be a better solution. In other cases, REST API should be sufficient.

What are webhooks?

A webhook is an element of an API that is designed for one-way data transfer and triggering a specific action. In practice, it means that it is an endpoint (a URL) that "waits" for a call from an external service along with certain data, which the endpoint then processes and performs the corresponding action. An example of a webhook could be marking an order as paid in a headless commerce solution. Let's imagine that we have an online store integrated with the PayU payment gateway. When a customer clicks the "Pay" button, they are redirected to the PayU page to complete the payment. After the payment is made, the PayU system sends a request to our webhook with the order number and its status (paid, unpaid, etc.). Upon receiving this information, the webhook locates the corresponding order in our system and updates its status to match the information received from PayU.

As seen in the examples above, thanks to the headless architecture, we can leverage APIs that offer numerous benefits that would not be possible with traditional ecommerce business platform. Headless commerce solutions built on APIs are taking over the e-commerce market and becoming the solution of the future.

Glossary of Terms

  • API (Application Programming Interface) - an interface in a headless platform that facilitates communication between the frontend and backend layers.
  • Backend - the layer in a headless application responsible for logical operations and storing headless content data.
  • Cloud server - a server on which an application is hosted, making it accessible to the world. This server is managed by an external provider (hosting provider) who ensures its stability, availability, and security.
  • Framework - an application "skeleton" that provides a set of tools and functions used for creating new solutions.
  • Frontend - the layer in a headless application (also known as headless ecommerce storefront) responsible for displaying information and facilitating user interaction with the application. It greatly influences the user experience and shopping experience in the case of headless commerce.
  • GraphQL - an API communication architecture that aims to retrieve pre-defined data.
  • Headless - an application architecture that separates the frontend layer from the backend layer.
  • Microservices - an application architecture that involves breaking it down into multiple small, independent components that communicate with each other through APIs and collectively create the entire application making highly customizable headless platform.
  • Monolith - an application architecture that tightly couples the database, backend, and frontend together.
  • PaaS (Platform-as-a-Service) - a set of services that provide a platform necessary for running applications for a specified recurring fee.
  • Platform - a combination of hardware (mechanical components of a computer) and software required to run an application.
  • Private VPS - a server which supports headless ecommerce hosting, making it accessible to the world. This server is self-managed, meaning that the aspects of stability, availability, and security fall under our responsibility.
  • Programming language - a set of rules, patterns, and assumptions that provide instructions to a computer on what to do.
  • REST (Representational State Transfer) - a set of principles for creating APIs.
  • SaaS (Software-as-a-Service) - a service that provides access to specific software for a specified recurring fee.
  • Software - a set of instructions that operate on a computer.
  • Webhook - an API element designed for one-way data reception and performing a specific action.


As you can see, the vocabulary and concepts used in headless commerce can be intricate and complex. I hope that after reading this text, the entire topic of headless will become much clearer for you.

Ready to migrate to headless?

Let's talk about your project

Other blog posts

Wholesale eCommerce: What Is It & How Does It Work?

In this article, we delve into the dynamic world of wholesale eCommerce, exploring how it is reshaping the traditional wholesale landscape...

How to Design B2B eCommerce Websites

This comprehensive guide will explore the essential elements of creating a b2b ecommerce website that not only meets the unique needs of business buyers but also enhances the overall customer experience.

Tell us about your project

Got a project in mind? Let's make it happen!

By clicking “Send Message” you grant us, i.e., Rigby, consent for email marketing of our services as part of the communication regarding your project. You may withdraw your consent, for example via hello@rigbyjs.com.
More information

Grzegorz Tomaka

Co-CEO & Co-founder

LinkedIn icon

Jakub Zbaski

Co-CEO & Co-founder

LinkedIn icon