Nouvel arrivage : 14 retours d’expérience Scout

Medusa Explained · Pricing · 4/4

Le module Pricing dans Medusa : comprendre les prix HT et TTC

Le module Pricing de Medusa conserve les montants des produits et choisit celui qui s’applique à une vente. Il indique aussi si ce montant inclut déjà la taxe, ce qui permet ensuite au panier de calculer correctement les totaux.

4 novembre 2026
Dans cet article

Un montant ne dit pas si la taxe est comprise

Une variante de chaussure de course possède un ensemble de prix, un PriceSet, qui contient un Price en euros :

{
  "currency_code": "eur",
  "amount": 120
}

Extrait simplifié : seuls les deux champs utiles ici sont montrés.

Ce 120 est un nombre d’euros, mais il reste incomplet pour vendre. Il peut s’agir d’un prix hors taxes (HT) : la taxe viendra s’y ajouter lors du calcul des totaux. Il peut aussi s’agir d’un prix toutes taxes comprises (TTC) : la part de taxe est déjà incluse dans ces 120 EUR. Une boutique qui vend aux particuliers en France affiche en général des prix TTC ; une boutique qui vend surtout aux entreprises raisonne souvent en HT.

Rien dans le Price ne porte cette distinction. Elle dépend du contexte de vente : la devise, ou la région où l’on vend. Medusa l’enregistre donc à part, dans une seule entité supplémentaire.

La préférence de prix : PricePreference

Une PricePreference déclare comment lire les montants dans un contexte donné. Pour dire que tous les prix en euros sont saisis taxes comprises :

{
  "attribute": "currency_code",
  "value": "eur",
  "is_tax_inclusive": true
}

Extrait simplifié : l’objet conservé a aussi un identifiant (préfixe prpref_) et des dates techniques.

Les trois champs se lisent comme une phrase :

  • attribute désigne le critère de contexte. Seuls deux critères sont pris en compte : currency_code et region_id.
  • value précise la devise ou la région concernée, ici eur. Pour une région, on y met son identifiant, par exemple reg_123.
  • is_tax_inclusive vaut true si les montants de ce contexte incluent la taxe. Sa valeur par défaut est false.

Il ne peut exister qu’une préférence par couple critère–valeur : une seule pour eur, une seule pour une région donnée. Et en l’absence de toute préférence applicable, Medusa considère les montants comme hors taxes.

Retenons un point essentiel : la préférence ne contient aucun taux. Elle dit comment interpréter un montant, pas combien de taxe s’y applique.

Créer et modifier la préférence

Le service du module Pricing expose les opérations attendues sur cette entité :

  • createPricePreferences enregistre une ou plusieurs préférences ;
  • updatePricePreferences change, par exemple, is_tax_inclusive d’une préférence existante ;
  • listPricePreferences retrouve les préférences, par exemple celle de la devise eur.

Dans une application, on passe rarement par le service directement. Le workflow createPricePreferencesWorkflow, utilisé par la route Admin de création, reçoit la même forme de données :

await createPricePreferencesWorkflow(container).run({
  input: [{ attribute: "currency_code", value: "eur", is_tax_inclusive: true }],
})

Créer cette préférence ne touche à aucun prix. Le Price de 120 EUR reste à 120 : Medusa ne convertit pas les montants existants, ne les divise pas et ne les réécrit pas. Seule change la façon de les lire. Passer une boutique de HT à TTC demande donc de revoir soi-même les montants saisis, si l’on veut conserver les mêmes montants taxes comprises.

Les mêmes réglages dans l’Admin

L’Admin de Medusa présente ce réglage à deux endroits. Dans Settings → Store, le tableau des devises de la boutique comporte une colonne Tax inclusive pricing. Dans la boutique de démonstration capturée, l’euro y est réglé sur False : ses prix sont lus hors taxes.

Réglages Store de l’Admin Medusa : tableau des devises avec la colonne Tax inclusive pricing, euro à False

La fiche d’une région, dans Settings → Regions, affiche la même information pour la région. Ici, la région de démonstration est en euros, couvre la France et n’est pas en prix taxes comprises.

Fiche d’une région dans l’Admin Medusa : devise EUR, Automatic Taxes à True, Tax inclusive pricing à False

Ces captures montrent l’emplacement du réglage ; leur valeur, False, diffère de l’exemple TTC ci-dessus, et elles n’illustrent aucun passage de l’un à l’autre. Ces deux écrans servent à consulter et modifier les préférences de devise et de région. L’Admin ne propose pas d’autre critère : les prix HT et TTC se règlent par devise ou par région.

Ce que Pricing renvoie

Au moment de vendre, le backend demande au module le prix applicable avec calculatePrices, en lui passant un contexte. Ce contexte doit contenir la devise ; on y ajoute la région pour prendre en compte une préférence régionale :

const [price] = await pricingModuleService.calculatePrices(
  { id: ["pset_01"] },
  { context: { currency_code: "eur" } }
)

Avec la préférence eur à true, la réponse ressemble à ceci :

{
  "currency_code": "eur",
  "calculated_amount": 120,
  "is_calculated_price_tax_inclusive": true,
  "original_amount": 120,
  "is_original_price_tax_inclusive": true
}

Extrait simplifié de la réponse : les autres champs sont omis.

calculated_amount est le montant retenu. is_calculated_price_tax_inclusive dit comment le lire : ici, 120 EUR taxes comprises. original_amount est le montant de référence, souvent identique quand aucun tarif particulier ne s’applique ; il reçoit son propre indicateur, is_original_price_tax_inclusive.

C’est tout ce que Pricing apporte à la question fiscale : un montant et la manière de l’interpréter. Il ne connaît pas le taux de TVA, ne crée pas de lignes de taxe et ne calcule pas le total du panier.

Qui calcule la taxe ?

Trois acteurs se partagent la suite.

Le module Tax connaît les taux. À partir de l’adresse ou du pays du client et de la région de vente, il fournit les taux et les lignes de taxe qui s’appliquent, en passant par un fournisseur de taxes (le fournisseur par défaut de Medusa, ou un service externe branché à sa place).

Les workflows du panier coordonnent l’ensemble. Quand une variante entre dans le panier, ils récupèrent le montant calculé par Pricing avec son indicateur HT/TTC, puis demandent au module Tax les lignes de taxe de chaque article.

Le calcul des totaux combine enfin les deux informations. Selon l’indicateur, il extrait la taxe d’un montant TTC ou l’ajoute à un montant HT.

Prenons un exemple isolé : une seule unité d’un article, sans autres frais ni remise, avec un taux supposé de 20 % :

  • montant TTC de 120 EUR : HT = 120 / (1 + 0,20) = 100 EUR, taxe = 120 − 100 = 20 EUR. La ligne vaut 120 EUR taxes comprises.
  • montant HT de 100 EUR : TTC = 100 × (1 + 0,20) = 120 EUR, dont 20 EUR de taxe.

Avec le même amount: 120 lu hors taxes, cette ligne atteindrait donc 144 EUR taxes comprises. C’est exactement l’écart qu’évite la préférence : la taxe n’est pas toujours « ajoutée », elle est parfois extraite.

Pour aller plus loin : devise et région en même temps

Une boutique peut avoir une préférence pour la devise et une autre pour une région. Si le contexte contient à la fois currency_code et region_id, Medusa ne donne pas automatiquement raison à la région. Elle l’emporte seulement si deux conditions sont réunies :

  1. le prix retenu est lui-même réservé à cette région (il porte une règle region_id égale à celle du contexte) ;
  2. cette région possède une préférence.

Sinon, c’est la préférence de la devise du prix qui s’applique ; et sans préférence du tout, le montant est lu hors taxes.

Par exemple, l’euro est en HT, mais la région France est en TTC. Une variante a un prix général de 100 EUR et un prix de 120 EUR réservé à la région France. Pour un client en France, si c’est le prix de 120 EUR qui est retenu, il est lu TTC. Pour une variante qui n’a que son prix général en euros, le montant est lu HT, même pour ce client en France.

Ce qu’on sait maintenant

Un amount: 120 n’est ni « 120 TTC » ni « 120 HT » par lui-même. Le Price porte un nombre et une devise ; la PricePreference qui s’applique au contexte, par devise ou par région, dit si ce nombre inclut la taxe. Changer cette préférence change la lecture des prix, pas les montants enregistrés : Medusa ne les convertit pas.

Sources

Un sujet à creuser ? Ajoutez cet article à votre discussion office hours.

Voir ma discussion