Medusa Explained · Pricing · 2/4
Le module Pricing dans Medusa : adapter un prix au contexte
Le module Pricing conserve les prix des variantes et choisit celui qui s'applique à une situation donnée. Cet article montre comment une simple règle permet à une même variante d'afficher un autre prix dans une région précise.
Dans cet article
Le point de départ
Une variante est reliée à un PriceSet, qui regroupe ses Price : chacun porte un montant, une devise et, si besoin, des bornes de quantité. Quand on appelle calculatePrices avec une devise, le module retient le prix qui correspond.
Prenons une basket vendue 90 EUR. La marque décide de la proposer à 92 EUR dans sa région Benelux, où elle vend par un autre circuit. Partout ailleurs, le prix reste 90 EUR. La devise est la même ; seule la région change. Il faut donc pouvoir dire au module : « ce montant-là ne vaut que pour cette région ».
Une règle attachée à un prix
Le 92 EUR est un second Price dans le même PriceSet que le 90 EUR. Ce qui le distingue, c'est qu'il porte une règle de prix : un objet PriceRule qui pose une condition sur le contexte de calcul.
Voici cette règle telle qu'elle est conservée, réduite à ses champs utiles :
{
"id": "prule_01",
"price_id": "price_92",
"attribute": "region_id",
"operator": "eq",
"value": "reg_benelux"
}
Autres champs techniques omis.
La lecture est directe : le prix price_92 ne s'applique que si le contexte contient region_id égal à reg_benelux. attribute nomme la donnée testée, value la valeur attendue, operator la comparaison ; eq, l'égalité, est la valeur par défaut. Le prix lui-même tient à jour un compteur rules_count, ici à 1. Le prix à 90 EUR n'a aucune règle : son rules_count vaut 0.
Un prix peut porter plusieurs règles, par exemple une région et un code postal. Dans ce cas, toutes devront être satisfaites. Cet article s'en tient à une seule.
Écrire la règle avec le prix
Ici, on déclare la règle en même temps que le prix, avec la méthode addPrices du service Pricing, qui ajoute des prix à un ensemble existant :
await pricingModuleService.addPrices({
priceSetId: "pset_basket_42",
prices: [
{
amount: 92,
currency_code: "eur",
rules: { region_id: "reg_benelux" },
},
],
})
Le champ rules est un paramètre d'entrée, pas l'objet stocké. C'est un simple dictionnaire { attribut: valeur }, pratique à écrire. Le module le transforme en une PriceRule par entrée, avec l'opérateur eq, et met à jour rules_count. Ce qu'on envoie et ce qui est conservé ont donc deux formes différentes ; le JSON précédent montre la seconde.
En pratique, dans une application Medusa, on passe le plus souvent par les workflows du produit plutôt que par le service Pricing directement. Le prix régional suit alors le même chemin que les autres prix de la variante.
Calculer avec et sans région
La règle est en place. Que renvoie maintenant calculatePrices ?
Sans région dans le contexte :
const [price] = await pricingModuleService.calculatePrices(
{ id: ["pset_basket_42"] },
{ context: { currency_code: "eur" } }
)
// price.calculated_amount : 90
Avec la région Benelux :
const [price] = await pricingModuleService.calculatePrices(
{ id: ["pset_basket_42"] },
{ context: { currency_code: "eur", region_id: "reg_benelux" } }
)
// price.calculated_amount : 92
Et avec region_id: "reg_france", le résultat redevient 90. La méthode renvoie un tableau, un objet par ensemble ; les commentaires n'en montrent que le montant calculé. Cet objet contient d'autres champs, comme le montant de référence et le prix retenu.
Le contexte est un objet JSON libre. currency_code est obligatoire ; quantity sert aux bornes de quantité ; toutes les autres clés sont comparées aux règles.
Comment le module choisit
Le choix se fait en deux temps : d'abord écarter les prix qui ne s'appliquent pas, ensuite classer ceux qui restent.
Être admissible. Un prix est candidat si sa devise et ses bornes de quantité conviennent, et si toutes ses règles sont satisfaites par le contexte. Une correspondance partielle ne suffit pas. Il en découle trois comportements :
- un prix sans règle reste candidat dans tous les contextes, tant que la devise et la quantité conviennent ;
- si le contexte ne contient pas
region_id, le prix à 92 EUR est exclu : sa règle ne peut pas être vérifiée ; - si le contexte contient une donnée qu'aucune règle n'utilise, par exemple un code pays, elle n'a aucun effet.
Être classé. Parmi les candidats, hors listes de prix, le module place d'abord les prix qui ont le plus de règles, puis, à égalité, le montant le plus bas.
Avec reg_benelux, les deux prix sont candidats : 90 EUR sans règle, 92 EUR avec une règle. Le 92 EUR passe devant parce qu'il est plus spécifique, alors qu'il est plus cher. Le module ne cherche donc pas le prix minimum : il cherche le prix le plus précis pour ce contexte, et ne départage par le montant qu'à précision égale.
Les bornes de quantité ne changent pas de nature avec les règles. Elles restent des champs du Price (min_quantity, max_quantity), filtrés avant le classement, et ne deviennent pas des objets PriceRule.
Qui fournit le contexte
Le module ne devine rien. Il ne sait pas où se trouve le client ni quel panier il consulte : il compare les règles au contexte qu'on lui passe.
C'est l'application qui prépare ce contexte. Côté boutique, les routes produits de la Store API acceptent par exemple un paramètre region_id, ou retrouvent la région à partir du panier, et transmettent ces informations au calcul avec la devise. Les données du client connecté sont ajoutées de la même façon côté serveur. Le module reste ainsi indépendant de la manière dont la région a été déterminée.
Dans l'Admin, la section Prices d'une variante affiche ses montants courants. L'interface native n'est pas pour autant un éditeur générique de règles : une règle sur un attribut propre à votre projet s'écrit par code ou par workflow.
Ce qu'on sait faire maintenant
Une règle de prix attache une condition à un montant. Pour vendre une variante 92 EUR au Benelux et 90 EUR ailleurs, il suffit d'ajouter au même PriceSet un prix porteur d'une règle region_id. Au calcul, un prix n'est admissible que si toutes ses règles sont satisfaites ; parmi les admissibles, le plus spécifique l'emporte, et le montant ne départage qu'à égalité. Le contexte vient du backend, et le module se contente de comparer.
Cette règle vit sur un seul prix d'une seule variante. Si une condition doit ouvrir des montants négociés sur des dizaines de variantes à la fois, par exemple pour un groupe de revendeurs, on peut la regrouper : c'est le rôle des listes de prix, sujet de l'article suivant.
Sources
- Documentation Medusa : règles de prix, dont les autres opérateurs disponibles ; calcul des prix.