Price Rules

In this Pricing Module guide, you'll learn about price rules for price sets and price lists, and how to add rules to a price.

Price Rule#

You can restrict prices by rules. Each rule of a price is represented by the PriceRule data model.

The Price data model has a rules_count property, which indicates how many rules, represented by PriceRule, are applied to the price.

For exmaple, you create a price restricted to 10557 zip codes.

A diagram showcasing the relation between the PriceRule and Price

A price can have multiple price rules.

For example, a price can be restricted by a region and a zip code.

A diagram showcasing the relation between the PriceRule and Price with multiple rules.


Price List Rules#

Rules applied to a price list are represented by the PriceListRule data model.

The rules_count property of a PriceList indicates how many rules are applied to it.

A diagram showcasing the relation between the PriceSet, PriceList, Price, RuleType, and PriceListRuleValue


How to Set Rules on a Price?#

Using Workflows#

Medusa uses the Pricing Module to store prices of different resources, such as product variants and shipping options.

When you manage one of these resources using Medusa's workflows or using the API routes that use them, you can set rules on a price using the rules property of the price object.

For example, when creating a shipping option using the createShippingOptionsWorkflow to create a shipping option, you can make the shipping price free based on the cart total:

Code
1const { result } = await createShippingOptionsWorkflow(container)2  .run({3    input: [{4      name: "Standard Shipping",5      service_zone_id: "serzo_123",6      shipping_profile_id: "sp_123",7      provider_id: "prov_123",8      type: {9        label: "Standard",10        description: "Standard shipping",11        code: "standard",12      },13      price_type: "flat",14      prices: [15        // default price16        {17          currency_code: "usd",18          amount: 10,19          rules: {},20        },21        // price if cart total >= $10022        {23          currency_code: "usd",24          amount: 0,25          rules: {26            item_total: {27              operator: "gte",28              value: 100,29            },30          },31        },32      ],33    }],34  })

In this example, you create a shipping option whose default price is $10. When the total of the cart or order using this shipping option is greater than $100, the shipping option's price becomes free.

Using Pricing Module's Service#

Note: For most use cases, it's recommended to use workflows instead of directly using the module's service.

When adding a price using the addPrices method of the Pricing Module's service, pass the rules property to a price object.

For example:

Code
1const priceSet = await pricingModule.addPrices({2  priceSetId: "pset_1",3  prices: [4    // default price5    {6      currency_code: "usd",7      amount: 10,8      rules: {},9    },10    // price if cart total >= $10011    {12      currency_code: "usd",13      amount: 0,14      rules: {15        item_total: {16          operator: "gte",17          value: 100,18        },19      },20    },21  ],22})

In this example, you set the default price of a resource (for example, a shipping option), to $10. You also add a conditioned price that sets the price to 0 when the cart or order's total is greater than or equal to $100.

How is the Price Rule Applied?#

The price calculation mechanism considers a price applicable when the resource that this price is in matches the specified rules.

For example, a cart object has an item_total property. So, if a shipping option has the following price:

Code
1{2  "currency_code": "usd",3  "amount": 0,4  "rules": {5    "item_total": {6      "operator": "gte",7      "value": 100,8    }9  }10}

The shipping option's price is applied when the cart's item_total is greater than or equal to $100.

You can also apply the rule on nested relations and properties. For example, to apply a shipping option's price based on the customer's group, you can apply a rule on the customer.group.id attribute:

Code
1{2  "currency_code": "usd",3  "amount": 0,4  "rules": {5    "customer.group.id": {6      "operator": "eq",7      "value": "cusgrp_123"8    }9  }10}

In this example, the price is only applied if a cart's customer belongs to the customer group of ID cusgrp_123.

Note: These same rules apply to product variant prices as well, or any other resource that has a price.
Was this page helpful?
Ask Anything
FAQ
What is Medusa?
How can I create a module?
How can I create a data model?
How do I create a workflow?
How can I extend a data model in the Product Module?
Recipes
How do I build a marketplace with Medusa?
How do I build digital products with Medusa?
How do I build subscription-based purchases with Medusa?
What other recipes are available in the Medusa documentation?
Chat is cleared on refresh
Line break