Skip to main content

How to Show Products on the Storefront

In this document, you’ll learn how to show products in your storefront using the Store REST APIs.

Overview​

Using the products store REST APIs, you can display products on your storefront along with their different details.

Scenario​

You want to add or use the following storefront functionalities:

  • List products with filters.
  • Display product prices.
  • Search products.
  • Retrieve details of a single product by ID or by handle.

Prerequisites​

Medusa Components​

It's assumed that you already have a Medusa backend installed and set up. If not, you can follow the quickstart guide to get started.

It's also assumed you already have a storefront set up. It can be a custom storefront or one of Medusa’s storefronts. If you don’t have a storefront set up, you can install the Next.js Starter Template.

JS Client​

This guide includes code snippets to send requests to your Medusa backend using Medusa’s JS Client, among other methods.

If you follow the JS Client code blocks, it’s assumed you already have Medusa’s JS Client installed and have created an instance of the client.

Medusa React​

This guide also includes code snippets to send requests to your Medusa backend using Medusa React, among other methods.

If you follow the Medusa React code blocks, it's assumed you already have Medusa React installed and have used MedusaProvider higher in your component tree.

@medusajs/product Module​

This guide also includes code snippets to utilize the @medusajs/product module in your storefront, among other methods.

If you follow the @medusajs/product code blocks, it's assumed you already have the @medusajs/product installed.

List Products​

You can list available products using the List Products endpoint:

medusa.products.list()
.then(({ products, limit, offset, count }) => {
  console.log(products.length)
})

This endpoint does not require any parameters. You can pass it parameters related to pagination, filtering, and more as explained in the API reference.

The request returns an array of product objects along with pagination parameters.

Filtering Retrieved Products​

The List Products endpoint accepts different query parameters that allow you to filter through retrieved results.

For example, you can filter products by a category ID:

medusa.products.list({
  category_id: ["cat_123"],
})
.then(({ products, limit, offset, count }) => {
  console.log(products.length)
})

This will retrieve only products that belong to that category.

Expand Categories​

To expand the categories of each product, you can pass categories to the expand query parameter:

medusa.products.list({
  expand: "categories",
})
.then(({ products, limit, offset, count }) => {
  console.log(products.length)
})

You can learn more about the expand parameter in the API reference

Product Pricing Parameters​

By default, the prices are retrieved based on the default currency associated with a store. You can use the following query parameters to ensure you are retrieving correct pricing based on the customer’s context:

  • region_id: The ID of the customer’s region.
  • cart_id: The ID of the customer’s cart.
  • currency_code: The code of the currency to retrieve prices for.

It’s recommended to always include the cart and region’s IDs when you’re listing or retrieving a single product’s details, as it’ll show you the correct pricing fields as explained in the next section.

For example:

medusa.products.list({
  cart_id,
  region_id,
})
.then(({ products, limit, offset, count }) => {
  console.log(products.length)
})

Display Product Price​

Each product object in the retrieved array has a variants array. Each item in the variants array is a product variant object.

Product prices are available for each variant in the product. Each variant has a prices array with all the available prices in the context. However, when displaying the variant’s price, you’ll use the following properties inside a variant object:

  • original_price: The original price of the product variant.
  • calculated_price: The calculated price, which can be based on prices defined in a price list.
  • original_tax: The tax amount applied to the original price, if any.
  • calculated_tax: The tax amount applied to the calculated price, if any.
  • original_price_incl_tax: The price after applying the tax amount on the original price.
  • calculated_price_incl_tax: The price after applying the tax amount on the calculated price

Typically, you would display the calculated_price_incl_tax as the price of the product variant.

You must pass one of the pricing parameters to the request to retrieve these values. Otherwise, their value will be null.

Prices in Medusa are stored as the currency's smallest unit. So, for currencies that are not zero-decimal, the amount is stored multiplied by a 100. You can learn more about this in the Product conceptual guide.

So, to show the correct price, you would need to convert it to its actual price with a method like this:

const convertToDecimal = (amount: number) => {
  return Math.floor(amount) / 100
}

To display it along with a currency, it’s recommended to use JavaScript’s Intl.NumberFormat. For example:

new Intl.NumberFormat("en-US", {
  style: "currency",
  currency: "eur",
}).format(convertToDecimal(amount))

Ideally, you would retrieve the value of the currency property from the selected region’s currency_code attribute.

Medusa React provides utility methods such as formatVariantPrice that handles this logic for you.

Here’s an example of how you can calculate the price with and without Medusa React:

import React, { useEffect, useState } from "react"
import Medusa from "@medusajs/medusa-js"

const medusa = new Medusa({ 
  baseUrl: "<YOUR_BACKEND_URL>", 
  maxRetries: 3, 
})

function Products() {
  const [products, setProducts] = useState([])

  useEffect(() => {
    medusa.products.list({
      // TODO assuming region is already defined somewhere
      region_id: region.id,
    })
    .then(({ products, limit, offset, count }) => {
      // ignore pagination for sake of example
      setProducts(products)
    })
  })

  const convertToDecimal = (amount) => {
    return Math.floor(amount) / 100
  }

  const formatPrice = (amount) => {
    return new Intl.NumberFormat("en-US", {
      style: "currency",
      // TODO assuming region is already defined somewhere
      currency: region.currency_code,
    }).format(convertToDecimal(amount))
  }
  
  return (
    <ul>
      {products.map((product) => (
        <>
          {product.variants.map((variant) => (
            <li key={variant.id}>{
              formatPrice(variant.calculated_price_incl_tax)
            }</li>
          ))}
        </>
      ))}
    </ul>
  )
}

export default Products

Search Products​

The Search functionality requires either installing a search plugin or creating a search service.

You can search products using the Search Products endpoint:

medusa.products.search({
  q: "Shirt",
})
.then(({ hits }) => {
  console.log(hits.length)
})

This endpoint requires the query parameter q being the term to search products for. The search plugin or service you’re using determine how q will be used to search the products. It also accepts pagination parameters as explained in the API reference.

The request returns a hits array holding the result items. The structure of the items depends on the plugin you’re using.

Retrieve a Product by ID​

You can retrieve the details of a single product by its ID using the Get a Product endpoint:

medusa.products.retrieve(productId)
.then(({ product }) => {
  console.log(product.id)
})

This endpoint requires the product’s ID to be passed as a path parameter. You can also pass query parameters such as cart_id and region_id which are relevant for pricing as explained in the Product Pricing Parameters section. You can check the full list of accepted parameters in the API reference.

The request returns a product object. You can display its price as explained in the Display Product Price section.

You can also retrieve the product's categories by passing the expand query parameter similar to the explanation in this section.

Retrieve Product by Handle​

On the storefront, you may use the handle of a product as its page’s path. For example, instead of displaying the product’s details on the path /products/prod_123, you can display it on the path /products/shirt, where shirt is the handle of the product. This type of URL is human-readable and is good for Search Engine Optimization (SEO)

You can retrieve the details of a product by its handle by sending a request to the List Products endpoint, passing the handle as a filter:

medusa.products.list({
  handle,
})
.then(({ products }) => {
  if (!products.length) {
    // product does not exist
  }
  const product = products[0]
})

As the handle of each product is unique, when you pass the handle as a filter you’ll either:

  • receive an empty products array, meaning the product doesn’t exist;
  • or you’ll receive a products array with one item being the product you’re looking for. In this case, you can access the product at index 0.

As explained earlier, make sure to pass the product pricing parameters to display the product's price.

You can also retrieve the product's categories by passing the expand query parameter as explained in the Expand Categories section.

See Also​

Was this page helpful?
© 2023 Medusa, Inc. All rights reserved.