Skip to main content

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 ProductCopy to Clipboard entity has many useful attributes, including:

  • titleCopy to Clipboard: The name of the product.
  • handleCopy to Clipboard: 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.
  • statusCopy to Clipboard: A string indicating the status of the product. Its values can be draftCopy to Clipboard, proposedCopy to Clipboard, publishedCopy to Clipboard, and rejectedCopy to Clipboard.
  • external_idCopy to Clipboard: 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 ProductCopy to Clipboard entity are explored in the next sections.

Customizing the Product Entity​

It’s common for developers to customize the ProductCopy to Clipboard 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 metadataCopy to Clipboard 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:

metadata = {
  "someKey": "someValue",
}
Report Incorrect CodeCopy to Clipboard

In more complex scenarios, you may need to add columns or relations to your ProductCopy to Clipboard 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 ProductOptionCopy to Clipboard entity. The entity has the attribute titleCopy to Clipboard indicating the name of the option (for example, Color). The entity is associated with the ProductCopy to Clipboard entity through the product_idCopy to Clipboard attribute and the productCopy to Clipboard relation. You can also access the options of a product from the ProductCopy to Clipboard entity using the optionsCopy to Clipboard relation.

The available values of each option are represented by the ProductOptionValueCopy to Clipboard entity. The entity has the attribute valueCopy to Clipboard which is a string holding the value of the option (for example, Blue).

The ProductOptionValueCopy to Clipboard entity is associated with the ProductOptionCopy to Clipboard through the option_idCopy to Clipboard attribute and the optionCopy to Clipboard relation. You can also access the values of an option from the ProductOptionCopy to Clipboard entity using the valuesCopy to Clipboard relation.

The ProductOptionValueCopy to Clipboard entity is also associated with a product variant using the variant_idCopy to Clipboard attribute and the variantCopy to Clipboard 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 Diagram

Product variants are represented by the ProductVariantCopy to Clipboard entity. The entity’s attributes include:

  • titleCopy to Clipboard: A string title of the product variant. This is different from the title in the ProductCopy to Clipboard entity.
  • product_idCopy to Clipboard: A string indicating which product this variant belongs to. You can also access the product through the productCopy to Clipboard relation if it’s expanded.
  • skuCopy to Clipboard: A string indicating the Stock Keeping Unit (SKU) of the variant. This, along with other attributes like barcodeCopy to Clipboard or upcCopy to Clipboard are useful to store inventory-related information.
  • inventory_quantityCopy to Clipboard: A number indicating the available inventory of the variant. This is only useful if you have manage_inventoryCopy to Clipboard disabled.
  • manage_inventoryCopy to Clipboard: 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. You can learn more in the Inventory Module documentation.
  • inventory_itemsCopy to Clipboard: A relation that gives you access to the inventory items of a variant when manage_inventoryCopy to Clipboard is enabled. You can learn more in the Inventory Module documentation.
  • variant_rankCopy to Clipboard: 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 optionsCopy to Clipboard relation, which is an array of ProductOptionValueCopy to Clipboard 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 pricesCopy to Clipboard relation, which is an array of MoneyAmountCopy to Clipboard items. MoneyAmountCopy to Clipboard is an entity used throughout Medusa to store prices in general.

The MoneyAmountCopy to Clipboard entity has the following attributes that are useful for a product variant:

  • currency_codeCopy to Clipboard: A string indicating the currency code this price is for. The currency can also be accessed through the currencyCopy to Clipboard relation.
  • amountCopy to Clipboard: A number indicating the price.
  • region_idCopy to Clipboard: An optional string indicating the ID of the region this price is for. The region can also be accessed through the regionCopy to Clipboard relation.
  • price_list_idCopy to Clipboard: An optional string indicating the ID of the price list this price is for. The price list can also be accessed through the price_listCopy to Clipboard relation.

Storing the Product Variant’s Price​

Although this is no requirement, it’s recommended to store the amountCopy to Clipboard as the price multiplied by a hundred. The Medusa admin dashboard and the Next.js storefront expect the price to be of that format, so when prices are displayed 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 ProductCopy to Clipboard 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_channelsCopy to Clipboard relation and accessing product.sales_channelsCopy to Clipboard. 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 ProductTypeCopy to Clipboard entity.

The ID of the product’s type is stored under the attribute type_idCopy to Clipboard. You can access the product’s type by expanding the typeCopy to Clipboard relation and accessing product.typeCopy to Clipboard.

ProductTag​

A product can be associated with one or more tags. A tag is represented by the ProductTagCopy to Clipboard entity.

You can access the product’s tags by expanding the tagsCopy to Clipboard relation and accessing product.tagsCopy to Clipboard, which is an array of product tags.

ProductCollection​

A product can be associated with a collection. A collection is represented by the ProductCollectionCopy to Clipboard entity.

The ID You can access the product’s collection by expanding the collectionCopy to Clipboard relation and accessing product.collectionCopy to Clipboard.

ProductCategory​

A product can be associated with a category. A category is represented by the ProductCategoryCopy to Clipboard entity.

You can access the product’s categories by expanding the categoriesCopy to Clipboard relation and accessing product.categoriesCopy to Clipboard, 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 DiscountConditionProductCopy to Clipboard entity which holds the IDs of the product and the discount condition.

See Also​