Nouvel arrivage : 14 retours d’expérience Scout

Medusa Extend · Cas pratique

Gérer le dépôt-vente avec Medusa

Des produits confiés à des boutiques. Des ventes, des retours, des écarts de stock. Comment organiser un système commercial de dépôt-vente dans Medusa ?

1 novembre 2026Conception · Cas pratique

Une boutique souhaite vendre les produits d'une marque sans les acheter à l'avance. La marque lui confie donc des produits, qui restent sa propriété jusqu'à leur vente. La boutique paie à la marque les produits vendus, selon ce qu'elles ont convenu. Les invendus peuvent être renvoyés à la marque : c'est le principe du dépôt-vente.

Le principe du dépôt-vente

La marque confie des produits à la boutique ; la boutique déclare ses ventes à la marque.

Marque

Boutique

Pour gérer cette activité avec plusieurs boutiques, l'outil dans Medusa doit permettre à la marque de :

  • préparer avec chaque boutique une demande de mise en dépôt, en révisant les références et les quantités, puis la valider ou l'annuler ;
  • suivre les envois et leur réception, ainsi que les quantités en transit et celles présentes dans chaque boutique ;
  • enregistrer les relevés de ventes que les boutiques déclarent pour chaque période ;
  • organiser et suivre les retours d'invendus, même lorsqu'ils regroupent des produits arrivés par plusieurs envois ;
  • conserver les inventaires transmis par les boutiques, les comparer au stock attendu et examiner les écarts avant de valider tout ajustement.

Ce suivi permet à la marque de consulter la situation de chaque boutique et d'avoir une vue d'ensemble pour piloter son activité de dépôt-vente.

S'appuyer sur les modules de Medusa

Medusa est un moteur e-commerce organisé en modules prêts à l'emploi. Chaque module gère les informations et les opérations d'un domaine du commerce. Plutôt que de réécrire la gestion du catalogue, des stocks et de la logistique, nous construisons notre système à partir de ces modules.

Notre système de dépôt-vente va s'appuyer sur cinq de ces modules :

  • Product gère le catalogue. Chaque variante correspond à une référence que la marque peut envoyer, vendre ou compter.
  • Stock Location référence les lieux de stockage, dont l'entrepôt de la marque et le lieu de chaque boutique partenaire.
  • Inventory tient, pour chaque référence et chaque lieu, la quantité en stock et les quantités réservées. Pour une boutique, la quantité en stock enregistrée forme son stock attendu : ce qu'elle devrait avoir d'après les envois, ventes et retours déjà saisis.
  • Fulfillment enregistre les envois, les références et quantités qu'ils contiennent, ainsi que les dates de préparation, d'expédition et de livraison.
  • Order enregistre les ventes, ici celles que déclarent les boutiques.

Les modules déjà disponibles

  • Product

    catalogue

  • Stock Location

    lieux

  • Inventory

    quantités

  • Fulfillment

    envois

  • Order

    ventes

Construire un module de dépôt-vente

Les modules natifs tiennent le catalogue, le stock, les envois et les ventes. Le dépôt-vente produit en plus des documents échangés entre la marque et chaque boutique : des accords, des déclarations, des comptages. Ces documents propres au dépôt-vente n'ont pas de modèle dédié dans Medusa. Nous avons besoin de conserver quatre types de documents :

  • Les demandes de mise en dépôt (Requests) : une boutique, les lignes proposées puis retenues pour chaque référence, les révisions successives et l'état de la demande.
  • Les relevés de ventes (Sales Reports) : une boutique, une période, une date de déclaration, les lignes déclarées avec quantités et montants, et l'état de traitement du relevé.
  • Les retours d'invendus (Returns) : un document global pour une boutique, qui peut regrouper des produits arrivés par plusieurs envois, avec les lignes déclarées puis reçues, sa date et son état.
  • Les inventaires (Stock Counts) : un comptage daté transmis par la boutique, les quantités comptées, l'écart initial avec le stock attendu, puis les explications et la décision retenues.

Ces documents gardent ce qui a été convenu ou déclaré. Les envois restent dans Fulfillment, avec leurs propres dates, et les ventes validées sont enregistrées dans Order.

Nous créons donc un module de dépôt-vente qui regroupe ces quatre ensembles. Ses entités sont les modèles qui enregistrent les documents et leurs lignes, avec leurs révisions lorsque l'historique compte.

Un module, quatre ensembles de données

Module de dépôt-vente

  • Demandes de mise en dépôt
  • Relevés de ventes
  • Retours d’invendus
  • Inventaires

Son service expose les opérations que le reste de l'application utilise : créer un document, le lire, lister ceux d'une boutique, le modifier, supprimer un brouillon, faire évoluer son état. MedusaService fournit les méthodes courantes de gestion des modèles. Le module y ajoute ses propres règles : une demande annulée, par exemple, ne peut plus être validée.

Des workflows pour orchestrer chaque opération

Chaque information a maintenant sa place. Il reste à les faire évoluer ensemble, car une même action de la marque touche souvent plusieurs modules. Envoyer des produits en dépôt, par exemple, fait avancer la demande dans le module de dépôt-vente, crée un envoi dans Fulfillment et déplace des quantités dans Inventory. Un workflow coordonne ces changements : il appelle dans l'ordre les opérations de chaque module, et chaque module applique ses propres règles.

Tant que la marque et la boutique discutent, seule la demande change. La créer, la réviser, la valider ou l'annuler ne réserve rien et ne déplace aucun stock. Une fois la demande validée, la marque peut préparer l'envoi. Le workflow crée alors l'envoi dans Fulfillment et réserve les quantités à l'entrepôt, pour qu'elles ne partent pas ailleurs. À l'expédition, il retire ces quantités du stock de l'entrepôt et libère la réservation. Quand la marque confirme la réception dans l'Admin, le workflow date la livraison dans Fulfillment et ajoute les quantités au stock de la boutique.

Entre l'expédition et la réception, les produits ont quitté le stock de l'entrepôt sans figurer encore dans celui de la boutique. Pour connaître les quantités en transit, la marque additionne celles des envois expédiés et pas encore reçus. Ce calcul suffit parce que, dans ce cas, chaque envoi est reçu en entier.

Où se trouvent les produits ? Exemple : 12 pièces
ÉvénementEntrepôtEn transitcalculéBoutique
Demande validée1200
Préparation de l’envoi12dont 12 réservées00
Expédition0120
Réception0012

Les ventes suivent un autre chemin : les produits ont déjà été livrés à la boutique, puis vendus à ses clients. Quand la marque valide un relevé, le workflow retire les quantités vendues du stock de la boutique et enregistre ces ventes dans Order. Ce workflow ne crée aucun nouvel envoi et ne retire le stock qu'une fois.

Workflow de validation d’un relevé de ventes

  • Dépôt-vente

  • Inventory

  • Order

Le retour d'invendus refait le trajet en sens inverse. Son transport s'enregistre dans Fulfillment comme un envoi de la boutique vers l'entrepôt, même s'il regroupe des produits arrivés par plusieurs envois. À l'expédition, les quantités quittent le stock de la boutique. À la réception, elles entrent dans celui de l'entrepôt.

Un retour pour plusieurs envois

Deux envois partent de l’entrepôt vers la boutique ; un seul retour d’invendus revient de la boutique vers l’entrepôt.

Entrepôt

Boutique

L'inventaire sert à vérifier le stock de la boutique, mais sa déclaration ne le modifie pas. Le workflow compare les quantités comptées au stock attendu à la date du comptage et fait apparaître les écarts. Un écart n'est pas forcément une perte : des ventes de la période peuvent ne pas encore avoir été déclarées. La marque vérifie donc d'abord s'il manque des relevés pour cette période. S'il en manque, elle les traite avant de décider d'un ajustement. L'inventaire garde son constat initial, sa date et le motif retenu. Si un écart demeure après ce traitement, la marque décide s'il faut ajuster le stock. Dans ce cas seulement, elle motive l'ajustement et le valide, puis le workflow modifie le stock de la boutique.

Examiner un écart d’inventaire

  1. Écart constaté

  2. Vérifier les relevés

  3. Décision humaine

    • Stock conservé
    • Ajustement motivé et validé

Une action peut aussi être lancée deux fois, ou s'interrompre en cours de route. Les workflows doivent donc garder la trace des mouvements déjà effectués, pour qu'une reprise ne retire ni n'ajoute deux fois les mêmes quantités.

Il faut enfin pouvoir déclencher ces workflows depuis une interface. L'Admin, l'interface d'administration de Medusa, appelle des routes d'API, et chaque route déclenche un workflow : créer une demande, préparer un envoi, valider un relevé. Un portail réservé aux boutiques disposerait de ses propres routes, limitées aux données de chaque boutique. Ces routes appelleraient les mêmes workflows.

Deux interfaces, les mêmes workflows

L’Admin passe par l’API Admin, le portail boutiques optionnel par l’API boutiques ; les deux appellent les mêmes workflows de dépôt-vente.

Utiliser le dépôt-vente dans l'Admin de Medusa

Pour explorer ce module, nous avons construit un prototype interactif de l'Admin. Ses écrans, comme les mouvements de stock et les commandes qu'ils affichent, sont simulés dans le navigateur avec des données de démonstration : rien n'y est encore relié au module serveur. Une marque, quatre boutiques et trois entreprises suffisent pour en faire le tour.

Accueil Consignment : table des opérations avec type, boutique, quantité, état et prochaine étape.Agrandir la capture
L'accueil réunit les 21 opérations, leur état et ce qui doit se passer ensuite.

Savoir qui doit agir

Dans le menu de l'Admin, un clic sur Consignment ouvre l'accueil du dépôt-vente ; trois sous-entrées mènent ensuite à Stock, Sales et Locations. L'accueil rassemble toutes les opérations dans une même table, filtrable par type et par état : demandes de mise en dépôt, retours, relevés de ventes et comptages. La colonne Next step répond à la question qu'on se pose en arrivant : qui doit agir ? Admin action signale une tâche pour la marque, Location une action attendue de la boutique, Delivery une livraison à confirmer. Une opération terminée indique No action needed, et un relevé enregistré renvoie directement à sa commande.

Le stock sous trois angles

La page Stock présente les mêmes unités confiées par boutique, par entreprise ou par produit. Elle distingue deux quantités : le stock comptabilisé (Book stock), encore enregistré pour la boutique, et le disponible (Available), encore à vendre. Les ventes déclarées en attente et les retours annoncés sont déjà exclus du disponible ; quand le relevé est enregistré ou le retour expédié, seul le stock comptabilisé diminue. Incoming et Returning montrent les unités en route, vers la boutique ou vers l'entrepôt.

Page Stock, vue By location : une ligne par boutique avec son entreprise, le disponible, les arrivées, les ventes et retours en attente, et les retours en route.Agrandir la capture
By location : chaque boutique, sa ville et son entreprise.
Page Stock, vue By company : StrideHouse Retail sur deux boutiques, Harbor Steps et Northgate Retail sur une.Agrandir la capture
By company : StrideHouse Retail additionne ses deux boutiques.
Page Stock, vue By product : chaque variante avec le nombre de boutiques qui la détiennent et ses quantités.Agrandir la capture
By product : chaque référence et le nombre de boutiques qui la détiennent.

Une entreprise, deux boutiques

Une même entreprise peut tenir plusieurs boutiques : StrideHouse Retail exploite StrideHouse à Lyon et Corner Run à Bordeaux. Sa fiche, ouverte depuis la vue By company, aligne les deux boutiques avec leur stock et leurs ventes, puis leur total. Deux onglets détaillent le stock et les ventes par produit, et chaque ligne mène à la boutique concernée.

Fiche StrideHouse Retail : deux boutiques avec disponible, stock comptable, unités vendues et montant, puis le total et le stock par produit.Agrandir la capture
StrideHouse Retail : les bilans de Lyon et de Bordeaux, puis leur total.

Une boutique et son historique

La fiche d'une boutique réunit ses opérations, son stock, ses ventes et son activité. La marque y demande un nouvel envoi ou un comptage. L'onglet Activity retrace chaque étape avec l'opération concernée et son origine : une action de la marque, ou une confirmation de la boutique saisie dans l'Admin.

Fiche de la boutique StrideHouse à Lyon, onglet Stock : quantités par produit et coordonnées de la boutique.Agrandir la capture
StrideHouse à Lyon : son stock par produit et ses coordonnées.
Onglet Activity de StrideHouse : chronologie des étapes, chacune avec son opération et son origine.Agrandir la capture
Activity : la chronologie de la boutique, de son ajout au dernier comptage.

Suivre une mise en dépôt

Une demande commence en brouillon, avec sa boutique et ses produits, puis elle est soumise à l'accord de la boutique. Une fois l'envoi expédié depuis l'entrepôt, ses unités apparaissent en Incoming et la page attend la confirmation de livraison. Le bouton Record receipt l'enregistre : les unités entrent alors dans le stock de la boutique.

Demande REQ-1003 à l'état Shipped : prochaine étape Delivery, bouton Record receipt, lignes de produits et activité.Agrandir la capture
REQ-1003 expédiée : 8 unités en route vers Corner Run, réception à confirmer.

Des ventes déclarées aux commandes

La page Sales reprend les trois vues du stock, sur une période choisie. Seuls les relevés enregistrés comptent dans le bilan. Un relevé soumis mais pas encore enregistré reste à part, sous Not yet recorded, comme les 8 unités déclarées par Harbor Steps ; les brouillons sont ignorés.

Page Sales, vue By location : unités vendues, montant, nombre de relevés et ventes pas encore enregistrées par boutique.Agrandir la capture
By location : unités, montants et ventes pas encore enregistrées.
Page Sales, vue By company : ventes enregistrées de chaque entreprise, StrideHouse Retail sur deux boutiques.Agrandir la capture
By company : les ventes des deux boutiques StrideHouse réunies.
Page Sales, vue By product : unités vendues et montant par variante, avec le nombre de boutiques.Agrandir la capture
By product : les références classées par montant vendu.

Enregistrer un relevé diminue le stock de la boutique et crée une commande dans Order. Relevé et commande restent distincts et se renvoient l'un à l'autre : SR-3001 affiche la commande #1041, qui rappelle à son tour son relevé, sa boutique et l'absence d'expédition, puisque les produits ont été vendus en boutique.

Relevé SR-3001 à l'état Recorded : quantités et prix par produit, période de septembre et lien vers la commande #1041.Agrandir la capture
SR-3001 enregistré : période, quantités, prix et commande créée.
Commande #1041 issue du relevé SR-3001 : articles, total, boutique StrideHouse et fulfillment non requis.Agrandir la capture
Commande #1041 : issue du relevé, sans expédition à préparer.

Retours et comptages

Un retour déclaré rend aussitôt ses unités indisponibles à la vente. La boutique l'expédie ensuite, puis l'entrepôt confirme sa réception.

Retour RET-2004 à l'état Accepted : la boutique doit expédier une veste, bouton Record shipment.Agrandir la capture
RET-2004 accepté : la boutique expédie la veste, l'Admin enregistre l'envoi.

Un comptage, lui, ne change rien tant qu'il n'est pas validé. La page compare quantité attendue et quantité comptée, et chaque écart demande un motif choisi ligne par ligne avant la validation, qui le transforme en ajustement.

Comptage CNT-4002 à l'état To reconcile : quantités attendues et comptées, écart de −1 et motif à choisir avant Validate count.Agrandir la capture
CNT-4002 à rapprocher : un écart de −1, motif à choisir avant validation.

Ce que le dépôt-vente montre de Medusa

Ce cas montre une façon d'étendre Medusa : réemployer les briques en place et leur ajouter un module pour ce qui appartient au métier. Produits, emplacements de stock, envois et commandes restent portés par les modules existants. Le module de dépôt-vente modélise les opérations avec les boutiques, leurs états et leurs règles, puis les workflows coordonnent chaque opération entre ce module et les autres, chacun conservant ses propres règles.

Pour la marque, le résultat se lit dans l'Admin de Medusa. Elle voit ce que chaque boutique détient, ce qui a été vendu et qui doit agir ensuite, et ses ventes rejoignent les commandes qu'elle suit déjà.

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

Voir ma discussion