In this document, you’ll learn what price lists are and how they work.
What are Price Lists
Price lists can be used to override products’ prices based on different conditions. Each price list you create can have its own options and conditions. A price list must override at least one product variant’s prices.
Example Use Cases
Price lists can be used for a variety of use cases including:
- Setting different prices for VIP customers.
- Creating sales that run through a specific period of time.
- Implement Buy X for Price Y sale model. In other words, buy X quantity of a product at the price of Y.
Price List Entity Overview
A price list is stored in the database as a PriceList entity. Some of its important attributes are:
type: The price list's type. Can be either a
status: The status of the price list. Can be
draft. If a price list is a
draft, its prices won't be applied even if its conditions are met.
starts_at: The date to start applying the price list.
ends_at: The date to stop applying the price list.
Price List Conditions
You can control when a price list is applied using a set of conditions. Only when these conditions are met can the price list be applied.
You can use any of the following conditions:
- Start and/or expiry date: You can set a start date, an end date, or both to define when the prices in the list should be applied.
- Customer group: You can choose a customer group to apply the prices for. Customers that belong to this group will see the prices you set in the list, which customers that don’t belong to the group can’t see.
- Minimum and/or maximum quantity: You can specify the minimum quantity, the maximum quantity, or both minimum and maximum quantities of a product variant required to be in the customer’s cart to apply a price in a price list.
- Region: You can specify a specific region where a price in the price list is available in. Only customers accessing your store from that region can see these prices.
- Currency Code: You can specify a currency code where a price in the price list is available in. Only customers accessing your store from regions that use this currency can see these prices.
How are Price Lists Applied
When a product or a line item is retrieved or manipulated on the storefront, Medusa determines its price using a Price Selection Strategy. The price selection strategy determines the best price to apply in a given context. Part of determining the price depends on the price list.
When the strategy calculates the prices of a product variant, it retrieves both the original and the calculated prices of the variant.
The original price depends on the selected region or currency code in the current context, where the region has higher precedence.
The calculated price is the lowest price among all retrieved prices. Retrieved prices can include the original price and the price lists that can be applied. Prices are retrieved based on the provided context, such as region ID or currency code.
Each variant in the response has the following properties:
original_price: The price based on the region or currency selected. You can also retrieve the original price with tax from the
calculated_price: The price retrieved from a price list, if there are any. If no price list matches the current context,
calculated_pricewill have the same value as
original_price. You can also retrieve the calculated price with tax from the
If both the
currency_code aren’t passed to the request, the values of these properties will be
The total of a line item depends on the price of a product variant. When the line item is created, the price of its underlying product variant is retrieved using the same process detailed in the previous section.
unit_price of the line item is set to the
calculated_price property of the product variant.
When creating, retrieving, or updating the line item using the API Routes, the line item’s totals are calculated. The following properties are returned as part of the API Routes' responses:
unit_price: The product variant’s calculated price.
unit_pricemultiplied by the quantity of the line item.
Since the line item belongs to a cart, there’s no need to pass the
currency_code to the requests. The cart’s region and currency are used to determine the context of the price selection.