asyavee/medusa-store
1
0
Fork 0
Code Issues Pull Requests Actions 2 Packages Projects Releases Wiki Activity

docs: conceptual and how-to docs for price lists and price selection strategy (#2259)

Browse Source 
* docs: price lists and price selection strategy

* added missing type property

* Removed duplicate links
This commit is contained in:
Shahed Nasser
2022-09-28 12:13:05 +03:00
committed by GitHub
parent 1e9b50af72
commit 0ffc5b48d7
4 changed files with 276 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

86
docs/content/advanced/backend/price-lists/index.md Normal file
View File

@@ -0,0 +1,86 @@
# Price Lists
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](../../../references/entities/classes/PriceList.md) entity. Some of its important attributes are:
- `type`: The price list's type. Can be either a `sale` or an `override`.
- `status`: The status of the price list. Can be `active` or `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](../price-selection-strategy/index.md#context-object). Part of determining the price depends on the price list.
:::info
This section explains how the price selection strategy uses price lists when it determines the price of a product variant. If you want full details on how the price selection strategy works, check out this documentation instead.
:::
### Product Variants
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 [context](../price-selection-strategy/index.md#context-object).
In the [Get Product](https://docs.medusajs.com/api/store/#tag/Product/operation/GetProductsProduct) and [List Product](https://docs.medusajs.com/api/store/#tag/Product/operation/GetProducts) endpoints, you must pass either the `region_id` or `currency_code` to retrieve the correct prices, as they are part of the price selection strategy context.
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 `original_price_incl_tax` property.
- `calculated_price`: The price retrieved from a price list, if there are any. If no price list matches the current context, `calculated_price` will have the same value as `original_price`. You can also retrieve the calculated price with tax from the `calculated_price_incl_tax` property.
If both the `region_id` and `currency_code` aren’t passed to the request, the values of these properties will be `null`.
### Line Items
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.
Then, the `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 endpoints, the line item’s totals are calculated. The following properties are returned as part of the endpoints’ responses:
- `unit_price`: The product variant’s calculated price.
- `subtotal`: The `unit_price` multiplied by the quantity of the line item.
Since the line item belongs to a cart, there’s no need to pass the `region_id` or `currency_code` to the requests. The cart’s region and currency are used to determine the context of the price selection.
---
## What’s Next 🚀
- Learn more about [price selection strategies](../price-selection-strategy/index.md).

66
docs/content/advanced/backend/price-selection-strategy/index.md Normal file
View File

@@ -0,0 +1,66 @@
# Price Selection Strategy
In this document, you’ll learn what a price selection strategy is.
:::note
If you’re interested to learn how to override the price selection strategy, check out [this documentation](./override.md) instead.
:::
## What's a Price Selection Strategy
Medusa provides many features and different ways to control the price of a product variant. This includes price lists and their different conditions, products’ original prices, and taxes.
Medusa uses the `PriceSelectionStrategy` class to retrieve the best price for a product variant for a specific context. This strategy is used whenever products and line items are retrieved or manipulated on the storefront.
---
## PriceSelectionStrategy Overview
The `PriceSelectionStrategy` class extends the `AbstractPriceSelectionStrategy` class. Its main method is the `calculateVariantPrice` which is used to retrieve a product variant’s price in a given context.
### calculateVariantPrice Method
Medusa uses this method to retrieve a product variant’s price when a product variant or line item is retrieved or manipulated. This includes when other entities that product variants and line items belong to are retrieved, such as products and carts respectively.
This method accepts two parameters:
1. The ID of the variant.
2. A [context](#context-object) object.
The method retrieves all the available prices of the variant based on the conditions in the context object.
It returns an object with the following properties:
1. `originalPrice`: The original price of the variant which depends on the selected region or currency code in the context object. If both region ID and currency code are available in the context object, the region has higher precedence.
2. `originalPriceIncludesTax`: A boolean value indicating whether the original price includes taxes or not. This is only available for [Tax-Inclusive Pricing](../taxes/inclusive-pricing.md).
3. `calculatedPrice`: The lowest price among the prices of the product variant retrieved using the context object.
4. `calculatedPriceIncludesTax`: A boolean value indicating whether the calculated price includes taxes or not. This is only available for [Tax-Inclusive Pricing](../taxes/inclusive-pricing.md).
5. `calculatedPriceType`: Either `default` if the `calculatedPrice` is the original price, or the type of the price list applied.
6. `prices`: an array of all the prices of the variant retrieved using the context object. It can include its original price and its price lists if there are any.
:::info
You can learn more about price lists and how they’re used in [this documentation](../price-lists/index.md).
:::
### Context Object
The context that is passed to the `calculateVariantPrice` method is an object that has the following optional properties:
- `cart_id`: The ID of the customer’s cart. This is used when the prices are being retrieved for the variant of a line item, as it is used to determine the current region and currency code of the context.
- `customer_id`: The ID of the customer. This is used to filter out price lists for a customer group that this customer doesn’t belong to.
- `quantity`: The quantity of the item in the cart. This is used to filter out price lists that have `min_quantity` or `max_quantity` conditions set.
- `region_id`: The ID of the region the customer is using.
- `currency_code`: The currency code the customer is using.
- `include_discount_prices`: A boolean value indicating whether price list prices should be retrieved or not.
- `tax_rates`: The tax rates to be applied. This is only used for [Tax-Inclusive Pricing](../taxes/inclusive-pricing.md).
---
## What’s Next 🚀
- Learn [how to override the price selection strategy](./override.md).
- Learn more about [price lists](./../price-lists/index.md).

111
docs/content/advanced/backend/price-selection-strategy/override.md Normal file
View File

@@ -0,0 +1,111 @@
# Override Price Selection Strategy
In this document, you’ll learn how to override Medusa’s price selection strategy to create a custom pricing strategy.
:::note
If you’re interested in learning what a price selection strategy is and how it works, check out [this documentation](./index.md) instead.
:::
## 1. Create Class
Create a TypeScript or JavaScript file in `src/strategies` of your Medusa server project with a class that extends the `AbstractPriceSelectionStrategy` class:
```typescript
import { AbstractPriceSelectionStrategy, IPriceSelectionStrategy, PriceSelectionContext, PriceSelectionResult } from "@medusajs/medusa";
import { EntityManager } from "typeorm";
export default class MyPriceListStrategy extends AbstractPriceSelectionStrategy {
withTransaction(manager: EntityManager): IPriceSelectionStrategy {
if (!manager) {
return this
}
return new MyPriceListStrategy()
}
async calculateVariantPrice(
variant_id: string,
context: PriceSelectionContext
): Promise<PriceSelectionResult> {
//TODO
}
}
```
You can use services or repositories in the strategy by adding them to the constructor and updating the parameters passed to the `MyPriceListStrategy` constructor in `withTransaction`. For example:
```typescript
export default class MyPriceListStrategy extends AbstractPriceSelectionStrategy {
private productsService: ProductService
constructor({
productsService
}) {
super()
this.productsService = productsService
}
withTransaction(manager: EntityManager): IPriceSelectionStrategy {
if (!manager) {
return this
}
return new MyPriceListStrategy({
productsService: this.productsService
})
}
//...
}
```
---
## 2. Implement calculateVariantPrice
Implement the price selection strategy you want inside the `calculateVariantPrice` method.
This method accepts the variant ID as a first parameter and the [context](./index.md#context-object) object as a second parameter.
This method must return an object having the following fields:
```typescript
{
originalPrice, //number | null
calculatedPrice, //number | null
prices // MoneyAmount[]
}
```
You can learn more about optional properties and the meaning behind every property [here](./index.md#calculatevariantprice-method).
---
## 3. Run Build Command
In your terminal, run the build command to transpile the files in the `src` directory into the `dist` directory:
```bash npm2yarn
npm run build
```
---
## Test it Out
Run your server to test it out:
```bash npm2yarn
npm run start
```
Then, try out your strategy using any of the [Products](https://docs.medusajs.com/api/store/#tag/Product) or [Carts](https://docs.medusajs.com/api/store/#tag/Cart) endpoints which include retrieving product variants and line items respectively. You should then see the prices in the response based on your implemented strategy.
---
## What’s Next 🚀
- Learn more about [price list selection strategy](./index.md).

13
www/docs/sidebars.js
View File

@@ -291,6 +291,11 @@ module.exports = {
type: "doc",
id: "advanced/backend/batch-jobs/customize-import",
},
{
type: "doc",
id: "advanced/backend/price-selection-strategy/override",
label: "Override Price Selection"
},
]
},
{
@@ -347,6 +352,14 @@ module.exports = {
id: "advanced/backend/taxes/inclusive-pricing",
label: "Tax Inclusive Pricing"
},
{
type: "doc",
id: "advanced/backend/price-lists/index"
},
{
type: "doc",
id: "advanced/backend/price-selection-strategy/index"
},
]
},
{