Products Architecture Overview
In this document, you’ll learn about Products in Medusa and their relation to other entities.
Overview
Products are items that a business sells to customers. Each product can have options and variants. Options are the different available attributes of a product, and variants are the salable combinations of these options.
For example, a product can have a “Color” option with values blue and green. You can then create two product variants from these options: one using the option value blue, and the other using the value green. This is just a simple example, as you can have multiple options and have variants combine values from each of these options.
Products can be associated with categories, collections, types, and more. This allows merchants to better organize products either internally or for their customers.
Product Entity Overview
The Product
entity has many useful attributes, including:
title
: The name of the product.handle
: A slug representation of the product’s title. This can be used in the storefront to generate human-readable URLs for products, which can be beneficial for Search Engine Optimization (SEO) purposes.status
: A string indicating the status of the product. Its values can bedraft
,proposed
,published
, andrejected
.external_id
: A string that can be used to store an ID of the product on an external system. This is useful if you’re migrating the product from an ecommerce platform to Medusa, or if you’re connecting Medusa’s products to an external service.
Other attributes of the Product
entity are explored in the next sections.
Customizing the Product Entity
It’s common for developers to customize the Product
entity, as there can be different use cases for each type of businesses.
In some simple cases, you might just need to store additional values within the entity without fully customizing it. For those cases, you can use the metadata
attribute. This is an object stored in the database as a JSONB type in the database. You can store inside it key-value data that is useful for your case:
In more complex scenarios, you may need to add columns or relations to your Product
entity. You can then extend the entity to make your customizations.
Product Option Overview
Each product is expected to have at least one option. Options are used to specify the different available properties of that product. Some examples of options are colors, sizes, or material.
Product Options are represented by the ProductOption
entity. The entity has the attribute title
indicating the name of the option (for example, Color). The entity is associated with the Product
entity through the product_id
attribute and the product
relation. You can also access the options of a product from the Product
entity using the options
relation.
The available values of each option are represented by the ProductOptionValue
entity. The entity has the attribute value
which is a string holding the value of the option (for example, Blue).
The ProductOptionValue
entity is associated with the ProductOption
through the option_id
attribute and the option
relation. You can also access the values of an option from the ProductOption
entity using the values
relation.
The ProductOptionValue
entity is also associated with a product variant using the variant_id
attribute and the variant
relation.
Product Variant Overview
Product variants are the actual salable item in your store. Each variant is a combination of the different option values available on the product. For example, if you have a color option and a size option, here are some variants that you might have:
- Variant A: Color blue and size large
- Variant B: Color green and size large
- Variant C: Color blue and size small
- Variant D: Color green and size small
And the list can go on.
You can’t have two product variants with the same values. For example, you can’t have another Variant E having the same option values as Variant B.
Product variants are represented by the ProductVariant
entity. The entity’s attributes include:
title
: A string title of the product variant. This is different from the title in theProduct
entity.product_id
: A string indicating which product this variant belongs to. You can also access the product through theproduct
relation if it’s expanded.sku
: A string indicating the Stock Keeping Unit (SKU) of the variant. This, along with other attributes likebarcode
orupc
are useful to store inventory-related information.inventory_quantity
: A number indicating the available inventory of the variant. This is only useful if you havemanage_inventory
disabled.manage_inventory
: A boolean value indicating whether Medusa should handle the management of the product variant’s inventory. This would allow you to handle your inventory data more accurately across different locations. Learn more in the Inventory Module documentation.inventory_items
: A relation that gives you access to the inventory items of a variant whenmanage_inventory
is enabled. Learn more in the Inventory Module documentation.variant_rank
: a number that can be used to decide the sort order of variants in a storefront.
You can also access the option values of a product variant through the options
relation, which is an array of ProductOptionValue
items.
Product Variant Pricing
As the product variant is the salable item in your store, the price of a product is specific to each product variant.
A product variant can have more than one price for different context. For example, a product variant can have a different price for each currency or region.
The prices of a product variant are available on the prices
relation, which is an array of MoneyAmount
items. MoneyAmount
is an entity used throughout Medusa to store prices in general.
The MoneyAmount
entity has the following attributes that are useful for a product variant:
currency_code
: A string indicating the currency code this price is for. The currency can also be accessed through thecurrency
relation.amount
: A number indicating the price.region_id
: An optional string indicating the ID of the region this price is for. The region can also be accessed through theregion
relation.price_list_id
: An optional string indicating the ID of the price list this price is for. The price list can also be accessed through theprice_list
relation.
Storing the Product Variant’s Price
You must store the amount
in a currency's smallest unit as an integer.
For example, if a variant's price is 10 USD, it's stored is 1000
, as in 1,000 cents.
For zero-decimal currencies, the amount is still stored as an integer without multiplying by a 100. For example, if a variant's price is ¥500, it's stored as 500
.
Zero-decimal Currencies
This logic of formatting the price is not handled in the backend. So, when you add a product variant using the Admin APIs, you must format the price as explained earlier. The backend stores the price as received from API requests.
In addition, the Medusa Admin dashboard and the Next.js Starter Template expect the price to be of that format, so when prices are displayed for currencies that are stored multiplied by a 100
, such as USD, they’re divided by a hundred. Also, when you add or update a product variant, its price is sent to the Medusa backend as the price multiplied by a hundred.
Displaying the Product Variant’s Price
When showing a product’s details to the customer in the storefront, you can pass in your requests query parameters that specify the customer’s context. For example, you can specify the customer’s region. This would retrieve the correct pricing of the product for each customer. You can learn more in this documentation.
Relations to Other Entities
This section explores the relations between the Product
entity and other entities in your Medusa backend.
SalesChannel
Sales channels define the different channels a business is selling its products in. A product can be available in some or all sales channels.
You can access a product’s sales channels by expanding the sales_channels
relation and accessing product.sales_channels
. It’s an array of sales channels the product is available in.
ProductType
A product can belong to a type, which is represented by the ProductType
entity.
The ID of the product ’s type is stored under the attribute type_id
. You can access the product’s type by expanding the type
relation and accessing product.type
.
ProductTag
A product can be associated with one or more tags. A tag is represented by the ProductTag
entity.
You can access the product’s tags by expanding the tags
relation and accessing product.tags
, which is an array of product tags.
ProductCollection
A product can be associated with a collection. A collection is represented by the ProductCollection
entity.
The ID You can access the product’s collection by expanding the collection
relation and accessing product.collection
.
ProductCategory
A product can be associated with a category. A category is represented by the ProductCategory
entity.
You can access the product’s categories by expanding the categories
relation and accessing product.categories
, which is an array of product categories.
DiscountConditionProduct
A discount can be specified for one or more products through discount conditions. The relation between a discount condition and a product is established through the DiscountConditionProduct
entity which holds the IDs of the product and the discount condition.