Octroi de mer sur PrestaShop : industrialiser le calcul OM / OMR / TVA locale pour les expéditions DOM-TOM

Vendre depuis la métropole vers la Martinique, la Guadeloupe ou la Réunion, ce n’est pas juste une histoire de transporteur. C’est aussi un calcul fiscal que PrestaShop, par défaut, ne sait pas faire.

Octroi de mer, octroi de mer régional, TVA locale : trois lignes qui s’empilent sur la facture, avec des taux différents selon le DOM et selon le produit. Et qui dépendent d’une donnée que la majorité des catalogues PrestaShop n’ont pas correctement remplie : le code HS (nomenclature douanière).

On a récemment industrialisé ce calcul sur une boutique PrestaShop qui expédie vers plusieurs DOM-TOM. Voici comment on s’y est pris, ce qu’on a appris, et comment réutiliser l’approche sur d’autres shops.

1. Pourquoi l’octroi de mer ne tient pas dans une règle de taxe PrestaShop

PrestaShop sait gérer une TVA. Il sait même gérer plusieurs taux selon les pays, et appliquer des règles par groupe de produits. Mais l’octroi de mer, c’est trois taxes empilées, dont deux qui varient selon la combinaison « produit + DOM de destination ».

Concrètement, pour un même produit :

• Le taux d’OM peut être de l’ordre de 5 % en Martinique et de 10 % en Guadeloupe
• L’OMR (octroi de mer régional) s’ajoute par-dessus, avec encore un autre taux
• La TVA locale (8,5 % en moyenne dans les DOM concernés, contre 20 % en métropole) vient se brancher sur le tout
• Et certains produits sont exonérés selon des grilles publiées par les conseils régionaux

Tenter de modéliser ça avec le système natif de PrestaShop, c’est créer des dizaines de groupes de taxes, multiplier les règles, et obtenir un BO impossible à maintenir. Sans parler de la mise à jour annuelle des grilles fiscales.

L’octroi de mer n’est pas une variante de la TVA. C’est un système fiscal parallèle, avec ses propres règles, qui doit être traité comme tel.

2. Modéliser les règles par zone DOM, pas par produit

La logique qu’on a retenue : une matrice « zone DOM × catégorie HS » qui retourne les trois taux applicables (OM, OMR, TVA locale) plus un éventuel flag d’exonération.

On a séparé les responsabilités comme ça :

• 👉 Un repository de règles fiscales qui expose l’API « donne-moi les taux pour ce code HS dans ce DOM »
• 👉 Un service de calcul qui prend un panier + une adresse de livraison et retourne le détail ligne par ligne
• 👉 Un module PrestaShop qui branche le service aux hooks du tunnel de commande

Avantage : la matrice fiscale est isolée. Quand un conseil régional publie sa nouvelle grille (ça arrive chaque année), on met à jour un seul fichier de données, pas vingt règles éparpillées dans le BO.

3. Les codes HS : la donnée sur laquelle tout repose

C’est le point qu’on sous-estime systématiquement au début d’un projet DOM-TOM.

Le code HS (Harmonized System), c’est une nomenclature douanière internationale à 6, 8 ou 10 chiffres qui catégorise chaque produit. Sans code HS propre sur chaque référence du catalogue, le calcul d’octroi de mer est impossible à industrialiser.

Sur la boutique qu’on a traitée, l’état des lieux initial ressemblait à ça :

• Une partie du catalogue avait des codes HS, mais souvent au mauvais niveau de précision
• Une autre partie n’en avait pas du tout
• Et quelques produits avaient un code HS qui ne correspondait plus à la réalité du produit après évolution du catalogue

La première phase du chantier, ça a été un travail de fond avec le client pour nettoyer la donnée produit avant même de toucher au moteur de calcul. Sans ça, on aurait livré un module techniquement correct mais qui sort des montants faux.

Un calcul fiscal n’est jamais meilleur que la donnée d’entrée. Sur les DOM-TOM, la donnée d’entrée s’appelle « code HS ».

4. Gérer les exonérations sans complexifier le module

Certains produits sont exonérés d’OM ou d’OMR sur certaines zones. C’est défini par des arrêtés régionaux, et ça change.

Plutôt que d’ajouter une logique conditionnelle dans le code, on a traité les exonérations comme une règle parmi les autres dans la matrice : un produit exonéré, c’est juste une ligne qui retourne un taux à 0 (avec un flag pour pouvoir l’afficher proprement sur la facture, ce qui est légalement requis).

Bénéfice direct : aucune branche spécifique dans le code de calcul. Toute l’intelligence est dans les données, pas dans la logique. C’est plus simple à tester, plus simple à maintenir, et beaucoup plus simple à mettre à jour quand une nouvelle grille tombe.

5. Brancher la logique dans le tunnel de commande

Le module se greffe sur trois moments du checkout :

• Mise à jour du panier : dès que l’adresse de livraison change pour un DOM, on recalcule les taxes ligne par ligne
• Étape de validation : on affiche le détail OM / OMR / TVA locale dans le récapitulatif, avec un libellé clair pour le client final
• Génération de la commande : les montants calculés sont persistés sur la commande pour traçabilité et compta

On a aussi pris le parti de loguer systématiquement le détail du calcul sur chaque commande DOM. Pas en debug verbeux, mais sous forme structurée : zone DOM, code HS appliqué, taux retenus, montant final. Ça nous a sauvés plusieurs fois pendant la phase de validation.

6. Valider sur des paniers représentatifs

Avant la mise en prod, on a fait passer la logique sur des paniers représentatifs pour chacune des destinations principales :

• Martinique — panier multi-produits avec mix de catégories soumises et exonérées
• Guadeloupe — cas avec produit à OMR spécifique
• Réunion — taux différents et cas d’exonération propres à la zone

Pour chaque panier, on a comparé le montant calculé par le module avec un calcul manuel fait par le client à partir des grilles officielles. Les écarts détectés à cette étape étaient toujours liés à un code HS imprécis sur le produit — jamais à la logique de calcul elle-même.

C’est exactement le genre de validation qui transforme un « ça a l’air de marcher » en « on sait pourquoi ça marche ».

7. Réutiliser l’approche sur une autre boutique

Si vous expédiez depuis la métropole vers les DOM-TOM avec PrestaShop, voici les prérequis pour transposer l’approche :

• 👉 Audit du catalogue : combien de produits ont un code HS exploitable, à quel niveau de précision, et qui valide leur exactitude côté métier
• 👉 Identification des zones servies : pas la peine de modéliser la Polynésie si vous n’expédiez que sur les DOM
• 👉 Accès aux grilles fiscales à jour : conseil régional de chaque zone, et un référent métier capable de les interpréter
• 👉 Convention claire avec la compta sur la façon dont les montants OM / OMR / TVA seront ventilés sur les pièces comptables

Sans ces quatre éléments, on déconseille de démarrer. Avec ces quatre éléments, le module se construit proprement.

Notre avis chez Mintfull

L’octroi de mer, c’est typiquement le sujet qu’on retrouve mal traité parce qu’il a été abordé en mode « patch ». On rajoute une règle, puis une deuxième, puis une troisième, et au bout d’un an le BO devient inmaintenable et personne ne sait expliquer pourquoi un panier sort tel montant.

Notre conviction, vérifiée sur ce projet : il faut traiter l’octroi de mer comme un système à part entière, avec sa propre matrice de règles et son propre service de calcul. Pas comme une extension du moteur de taxes natif.

L’autre point sur lequel on n’a pas envie de transiger : la donnée produit. Tant que les codes HS ne sont pas propres, on refuse de mettre en prod un calcul automatique. La pire situation, c’est un module qui sort des montants faux que personne ne contrôle parce qu’on lui fait confiance.

Pour aller plus loin sur la qualité technique d’une boutique PrestaShop, on a aussi écrit sur l’optimisation PrestaShop et la maintenance via un contrat TMA.

FAQ

L’octroi de mer s’applique-t-il à toutes les expéditions vers les DOM ?
Non. Certains produits sont exonérés selon des grilles publiées par chaque conseil régional, et les taux varient selon le DOM de destination. C’est précisément pourquoi un calcul automatique est nécessaire dès qu’on a un catalogue de plus de quelques dizaines de références.

Pourquoi ne pas utiliser le moteur de taxes natif de PrestaShop ?
Parce qu’il est conçu pour gérer une seule taxe par produit-pays, alors que l’octroi de mer empile trois taxes (OM, OMR, TVA locale) dont les taux dépendent de la combinaison produit + zone. Modéliser ça en règles natives donne un BO ingérable.

Que se passe-t-il si un produit n’a pas de code HS ?
Soit on bloque le calcul et on remonte une erreur (notre choix par défaut), soit on applique un taux par défaut sur la zone — mais cette deuxième option fait porter un risque fiscal au marchand. Mieux vaut nettoyer la donnée produit en amont.

À quelle fréquence les grilles fiscales changent-elles ?
Au minimum une fois par an, parfois plus selon les zones et les décisions des conseils régionaux. C’est pour ça qu’on isole la matrice fiscale dans un fichier de données séparé : la mise à jour annuelle ne touche pas le code.

Combien de temps prend l’intégration sur une boutique existante ?
La partie technique se livre en deux à trois semaines selon la complexité du catalogue. Mais le préalable indispensable, c’est le nettoyage des codes HS — et cette phase, c’est souvent plusieurs semaines de travail côté équipe produit du marchand.

Le module fonctionne-t-il aussi pour la Guyane ou Mayotte ?
Oui, la matrice est extensible : il suffit d’ajouter la zone et les règles correspondantes. Le code de calcul ne change pas, c’est juste de la donnée à ajouter.

Vous expédiez vers les DOM-TOM et vos calculs d’octroi de mer ressemblent à une boîte noire ? On peut vous aider à les remettre à plat proprement. Notre équipe traite ce type de sujet régulièrement sur PrestaShop — parlons de votre boutique.