Intégration de l’API Walmart Marketplace : guide développeur

Ce que couvre l’API Walmart Marketplace

L’API Walmart Marketplace est un ensemble de points de terminaison REST disponibles sur marketplace.walmartapis.com. Elle permet à un vendeur, ou à un Solution Provider agréé agissant pour le compte de vendeurs, de gérer les articles, les stocks, les prix, les commandes, les retours, les rapports et les notifications sur Walmart.com sans ouvrir Seller Center. Ce guide porte sur le portail développeur du Marketplace américain ; les portails du Canada, du Mexique et du Chili sont distincts.

Une intégration fonctionnelle repose sur quatre éléments. L’ordre ci-dessous correspond à l’ordre recommandé pour les construire et diffère légèrement de celui présenté dans la vue d’ensemble de Walmart.

Les commandes passent volontairement avant le stock. Dès que vous envoyez une quantité positive pour un article actif, des commandes peuvent arriver. Une intégration capable de publier et de stocker des articles, mais pas encore d’accuser réception des commandes ni de les expédier, prépare une rupture suivie d’une survente. Maintenez donc les quantités à zéro jusqu’à ce que le parcours de commande fonctionne de bout en bout. Les rapports, insights, annonces, retours et Walmart Fulfillment Services (WFS) peuvent être ajoutés ultérieurement.

Intégration directe ou Solution Provider agréé ?

Votre approche dépend du compte Walmart auquel votre code accède. Ce choix modifie vos identifiants, votre parcours d’autorisation et même vos limites de requêtes.

Selon la documentation de Walmart, les nouveaux Solution Providers doivent utiliser OAuth 2.0 et non l’ancien modèle d’accès délégué. Les limites sont attribuées par vendeur ; les appels directs du vendeur et ceux d’une application de Solution Provider agréée sont comptabilisés séparément. Si un fournisseur publie plusieurs applications, chacune dispose de son propre quota.

Si Walmart fait partie des différents canaux que vous devez synchroniser, notre service d’intégration de marketplaces couvre Walmart ainsi que Amazon SP-API, eBay, Etsy, Temu, Shein et Shopee, notamment pour les fiches produit, les stocks, les commandes et le suivi.

Authentification de l’API Walmart Marketplace (OAuth 2.0)

Chaque appel à l’API Marketplace inclut un jeton d’accès OAuth 2.0 dans l’en-tête WM_SEC.ACCESS_TOKEN, ainsi que WM_SVC.NAME défini sur Walmart Marketplace. Le jeton provient du Token API à l’adresse https://marketplace.walmartapis.com/v3/token et reste valide pendant 15 minutes ; la réponse indique expires_in à 900 secondes. Le Token API prend en charge trois types de grant : client credentials, authorization code et refresh token.

Le Client ID et le Client Secret ne correspondent pas à l’ancien Consumer ID et à l’ancienne Private Key. L’ancienne méthode imposait de signer chaque requête ; OAuth supprime cette signature et réduit le nombre d’en-têtes. Le portail sépare les Production Keys et les Sandbox Keys, et permet de consulter à nouveau un secret lorsque nécessaire.

Le client ci-dessous met le jeton en cache et le renouvelle une minute avant son expiration. Vérifiez les noms des en-têtes et la requête adressée au Token API dans la documentation de référence avant la mise en production : cet exemple a été rédigé à partir de la documentation et n’a pas été exécuté avec un compte vendeur actif.

import time
import uuid
import requests

TOKEN_URL = 'https://marketplace.walmartapis.com/v3/token'


class WalmartAuth:
    def __init__(self, client_id, client_secret):
        self.client_id = client_id
        self.client_secret = client_secret
        self._token = None
        self._expires_at = 0.0

    def invalidate(self):
        self._token = None

    def token(self):
        # refresh 60 seconds early so no call starts with a dying token
        if self._token is None or time.time() > self._expires_at - 60:
            resp = requests.post(
                TOKEN_URL,
                auth=(self.client_id, self.client_secret),
                headers={
                    'Accept': 'application/json',
                    'WM_SVC.NAME': 'Walmart Marketplace',
                    'WM_QOS.CORRELATION_ID': str(uuid.uuid4()),
                },
                data={'grant_type': 'client_credentials'},
                timeout=30,
            )
            resp.raise_for_status()
            body = resp.json()
            self._token = body['access_token']
            self._expires_at = time.time() + int(body['expires_in'])
        return self._token

    def headers(self):
        return {
            'WM_SEC.ACCESS_TOKEN': self.token(),
            'WM_SVC.NAME': 'Walmart Marketplace',
            'WM_QOS.CORRELATION_ID': str(uuid.uuid4()),
            'Accept': 'application/json',
        }

Les erreurs fréquentes dans les intégrations d’authentification

• Un jeton par requête. Avec des jetons valables 15 minutes, il peut être tentant d’en demander un nouveau pour chaque tâche. Mettez-le en cache et, si plusieurs workers sont utilisés, partagez ce cache ou protégez le renouvellement avec un verrou afin d’éviter que dix workers ne le renouvellent simultanément.
• Des exemples de code obsolètes. Au moins un guide consacré à l’inventaire groupé affiche encore un en-tête Authorization Basic construit avec une consumer key et un secret. OAuth est désormais la méthode exigée par la documentation : considérez comme hérités les exemples qui signent les requêtes ou utilisent Consumer ID.
• Des tentatives illimitées après une erreur 401. En cas de 401, invalidez le jeton et réessayez une fois. Une seconde 401 indique des identifiants incorrects, un mauvais environnement (clé sandbox utilisée en production) ou un scope insuffisant ; une boucle de tentatives ne résoudra rien.
• Des problèmes de scope. OAuth associe un scope à chaque jeu d’identifiants et Walmart rejette les appels qui sortent de ce périmètre. Les identifiants vendeur disposent d’un accès complet ; ceux associés à un scope plus étroit sont refusés pour les appels qui le dépassent.

Limites de l’API Walmart et erreurs 429

Walmart applique deux types de limites : un débit de requêtes par API, qui renvoie 429 Too Many Requests lorsqu’il est dépassé, et une taille maximale de fichier par type de flux, qui renvoie 413 Payload Too Large. Les limites reposent sur un token bucket. Chaque appel consomme un jeton et le compartiment se recharge à un rythme fixe : une limite de 20 requêtes par heure peut donc ajouter une requête toutes les trois minutes au lieu de se réinitialiser à l’heure pleine.

Chaque réponse contient votre budget restant pour l’API concernée dans l’en-tête x-current-token-count, ainsi que l’heure de la prochaine augmentation du compteur. Les deux pages de documentation nomment différemment ce second en-tête (X-Next-Replenishment-Time sur la page des limites et x-next-replenish-time dans la FAQ) : prenez en charge les deux variantes et consignez celle que vous recevez réellement.

Voici les limites par défaut publiées pour les particuliers et les petites entreprises, tirées de la page de Walmart consacrée aux limites. Consultez-la pour obtenir le tableau complet, qui couvre également les points de terminaison WFS, insights, rapports et publicité.

Concevoir l’intégration en tenant compte des limites

• Gérez le budget par vendeur, pas par processus. Les limites appartiennent au compte vendeur. Une intégration multi-tenant doit donc prévoir un compartiment par vendeur connecté. Un limiteur global pénaliserait les petits vendeurs ou permettrait à un vendeur important d’épuiser le budget des autres.
• Mettez l’item spec en cache. La récupération de l’item spec autorise 10 appels par minute. Récupérez chaque version une fois, stockez-la et validez localement les charges utiles avant de consommer une soumission de flux.
• Interrogez les flux à moindre coût et récupérez les rapports avec parcimonie. La limite de 5000 interrogations par minute laisse une marge confortable, contrairement aux 60 rapports d’erreurs par heure. Téléchargez ce rapport uniquement lorsqu’un état signale des erreurs au niveau des lignes.
• Appliquez un backoff avec jitter en cas de 429. Un délai exponentiel accompagné d’une composante aléatoire évite que tous les workers ne réessaient en même temps.

import random
import time
import requests


def call_walmart(auth, method, url, max_attempts=5, **kwargs):
    resp = None
    refreshed = False
    for attempt in range(max_attempts):
        resp = requests.request(
            method, url, headers=auth.headers(), timeout=60, **kwargs
        )
        if resp.status_code == 401 and not refreshed:
            refreshed = True
            auth.invalidate()  # one fresh token per call, then give up
            continue
        if resp.status_code != 429:
            return resp
        # record the remaining budget; the docs spell the second header two ways
        print(
            'walmart throttle',
            resp.headers.get('x-current-token-count'),
            resp.headers.get('X-Next-Replenishment-Time')
            or resp.headers.get('x-next-replenish-time'),
        )
        time.sleep(min(2 ** attempt, 60) + random.random())
    return resp

Configurer les articles avec les flux et l’item spec 5.0

La création et la mise à jour des articles passent par la Bulk Item Setup API, un point de terminaison de flux : vous envoyez une requête POST à /v3/feeds avec un paramètre feedType et recevez un identifiant de flux. Une requête peut contenir jusqu’à 10 000 articles. Walmart recommande de maintenir le fichier sous 25 Mo pour garantir un traitement rapide ; 50 Mo sont autorisés pour les flux d’adaptation automobile FITMENT_ACES et FITMENT_PIES. Vous pouvez envoyer le fichier en pièce jointe ou placer la charge JSON dans le corps de la requête.

Le contenu des articles est validé par rapport à un item spec, qui évolue rapidement. Walmart a publié une nouvelle version 5.0 le 14 mai 2026, une autre le 22 juin 2026, puis annoncé une nouvelle version recommandée le 28 juillet 2026, selon l’avis de Walmart sur l’item spec de juillet 2026. Cela représente trois versions en moins de douze semaines, applicables à MP_ITEM, MP_MAINTENANCE, MP_WFS_ITEM et OMNI_WFS.

Deux conséquences pratiques en découlent. Premièrement, ne codez jamais en dur la version de l’item spec : lisez la version recommandée dans le tableau de suivi et des versions de l’Item spec, récupérez le schéma correspondant et stockez la version avec chaque flux envoyé afin de pouvoir relier un rejet à une modification du spec. Deuxièmement, la version de juillet a ajouté l’attribut item_assortment_type pour les articles de collection dans 20 types de produits supplémentaires. Seuls les vendeurs approuvés pour le programme Collectibles peuvent envoyer les champs propres aux objets de collection. Un mapping de catalogue qui renseigne tous les attributs facultatifs disponibles entraînera donc le rejet des vendeurs non approuvés.

Un flux est accepté avant d’être appliqué

Une réponse réussie au POST signifie que Walmart a reçu le fichier, pas que vos articles sont actifs. Le résultat arrive plus tard, au niveau de chaque ligne, via la Feed Status API. Construisez la boucle ainsi : envoyer, enregistrer l’identifiant du flux, interroger son état, puis traiter les résultats article par article : marquer les articles publiés, mettre en file les corrections nécessaires et récupérer le rapport d’erreurs uniquement ensuite. Renvoyer tout le flux parce que trois lignes ont échoué consomme une soumission et renvoie les 9997 lignes qui étaient correctes.

def submit_feed(auth, feed_type, path):
    url = 'https://marketplace.walmartapis.com/v3/feeds'
    with open(path, 'rb') as fh:
        data = fh.read()  # bytes, so a 429 retry can resend the body
    resp = call_walmart(
        auth, 'POST', url,
        params={'feedType': feed_type},
        files={'file': (path, data)},
    )
    resp.raise_for_status()
    return resp.json()['feedId']

Synchroniser les stocks et les prix avec l’API Walmart

La gestion du stock propose trois points d’entrée ; le choix dépend principalement du volume et de l’urgence.

Le flux groupé accepte le JSON en spec 1.5 (multi-nœuds) ou 1.4 (nœud unique), ainsi que le XML en spec 1.4. Comme les flux d’articles, il renvoie un identifiant de flux et fournit les résultats au niveau des lignes via la Feed Status API.

Pour les prix, Walmart propose désormais une API de gestion des prix et promotions avec une option groupée, et classe l’ancienne Price management API comme obsolète. Appuyez-vous sur la nouvelle API. Le flux PRICE_AND_PROMOTION est limité à 10 requêtes par heure : concevez votre système autour de cette limite. Un flux de prix doit être planifié par lots, et non déclenché à chaque modification.

Un modèle de synchronisation qui résiste aux limites

• Conservez une outbox des modifications, pas un calendrier de publications complètes. Enregistrez chaque changement de stock ou de prix, regroupez les changements successifs du même SKU, puis envoyez-les.
• Séparez les flux selon leur urgence. Envoyez les changements de stock faible ou nul par appels unitaires, jusqu’à 200 par minute, et le reste dans des flux groupés. Une quantité passant de deux à zéro ne doit pas attendre dans une file.
• Effectuez une réconciliation à un rythme plus lent. Lancez régulièrement un flux complet pour corriger les écarts et considérez-le comme une passe de réparation, pas comme la synchronisation principale.
• Écoutez l’état connu par Walmart. Les événements webhook tels que inventory out of stock, offer published et offer unpublished indiquent l’état perçu par Walmart, souvent l’endroit où un écart apparaît en premier.

Récupérer, confirmer et expédier les commandes Walmart

Chaque ligne de commande suit un petit nombre de statuts : Created (commande passée et prête à être confirmée), Acknowledged (commande confirmée et dont l’exécution est prévue), Shipped (expédiée avec un numéro de suivi), Canceled et Delivered. Le parcours opérationnel consiste à récupérer les commandes libérées, à confirmer chacune d’elles, à l’expédier avec un transporteur et un numéro de suivi, puis à gérer les annulations et remboursements lorsqu’ils surviennent.

Vous pouvez détecter les nouvelles commandes en interrogeant les points de terminaison de commande ou en vous abonnant aux événements webhook. Walmart propose notamment les événements purchase order created, purchase order line auto-canceled et order intent to cancel. La création d’abonnements est autorisée 200 fois par minute avec les limites par défaut.

Règles de traitement pour éviter les expéditions en double

• Partez du principe que la livraison est « au moins une fois ». Si vous utilisez à la fois les webhooks et l’interrogation, la même commande d’achat arrivera deux fois. Identifiez vos enregistrements par l’identifiant de commande d’achat et le numéro de ligne, et rendez les opérations de confirmation et d’expédition idempotentes.
• Conservez l’interrogation comme solution de secours. Un webhook jamais reçu est invisible. Une interrogation périodique des commandes libérées comble cette lacune à faible coût.
• Expédiez par ligne. Le point de terminaison d’expédition fonctionne sur les lignes de commande et est limité à 60 appels par minute. Regroupez donc une commande comportant plusieurs lignes en un seul appel plutôt qu’en un appel par ligne.
• Envoyez les vraies informations du transporteur et du suivi. Walmart publie une liste de noms de transporteurs pris en charge et expose des indicateurs de performance vendeur, tels que le taux de suivi valide et le taux d’expédition à temps, via ses Insights APIs. Faites explicitement correspondre vos transporteurs aux noms Walmart plutôt que d’envoyer du texte libre.
• Respectez la structure des frais. Les lignes de commande comportent des frais PRODUCT et SHIPPING, et un frais SHIPPING doit inclure shipDateTime en UTC. Convertissez les horodatages à la frontière du système et stockez-les en UTC en interne.

Walmart documente également un guide de migration Multi-Line Multi-Quantity (MLMQ). Si vous utilisez un ancien code d’intégration ou une bibliothèque tierce, vérifiez qu’il ne suppose pas qu’une commande contient toujours une seule ligne et une seule quantité.

Tester dans la sandbox Walmart avant la mise en production

Walmart propose deux environnements sandbox. La sandbox statique fournit des identifiants sandbox, des recommandations pour tester les Marketplace APIs, des validations de flux et sa propre page de limites. La sandbox dynamique propose des scénarios pour valider l’exécution des commandes, les retours, les remboursements et les stocks hors WFS. Les clés sandbox sont délivrées séparément des clés de production dans le Developer Portal.

La sandbox possède ses propres limites : un test réussi n’indique donc pas la marge disponible en production. Utilisez-la pour vérifier la correction de l’intégration et appuyez-vous sur la page des limites pour planifier la capacité.

Avant de basculer en production, testez volontairement les erreurs et pas seulement le parcours nominal :

1. Laissez un jeton expirer en cours d’exécution et vérifiez que le client le renouvelle une seule fois avant de poursuivre.
2. Provoquez une 429 et vérifiez que le backoff s’active et que les en-têtes de budget restant sont consignés.
3. Envoyez un flux contenant des lignes valides et invalides et vérifiez que seules les lignes en échec sont mises en file pour correction.
4. Livrez deux fois la même commande, via webhook et interrogation, et vérifiez qu’une seule confirmation et une seule expédition sont effectuées.
5. Faites traiter par l’analyseur une réponse contenant un champ supplémentaire et une valeur d’énumération inconnue, puis vérifiez qu’il ne plante pas.

Maintenir une intégration Walmart : obsolescences et changelog

Walmart a publié un Marketplace API Deprecation Guide le 11 mars 2026. Il définit les étapes Legacy (toujours pris en charge, mais déconseillé pour les nouvelles intégrations), Deprecated (suppression planifiée avec une date d’obsolescence et une date de fin publiées) et Sunset, en plus des API Active entièrement prises en charge. Le statut est publié dans la documentation et communiqué via les en-têtes de réponse de l’API. Une intégration qui consigne ces en-têtes peut donc être avertie directement par l’API.

Il existe également un changelog centralisé des API américaines, introduit en avril 2025. Ses entrées listent les API, paramètres, propriétés de réponse et valeurs d’énumération ajoutés ou supprimés, ainsi que les propriétés qui passent de requises à facultatives ou inversement. Les entrées récentes, comme la version du 23 juillet 2026, ajoutent principalement des champs facultatifs dans les requêtes et les réponses. C’est la forme habituelle des changements et cela plaide pour une analyse tolérante : ignorez les champs inconnus et ne traitez jamais une valeur d’énumération inconnue comme une erreur fatale.

Les obsolescences concernent bien des points de terminaison réels. La navigation du portail développeur indique actuellement que l’ancienne Price management API et la Simplified Shipping Settings API sont obsolètes. Une modification antérieure de Price Incentives a également remplacé le point de terminaison CPpreference par un nouveau, l’ancien devant être retiré après le 30 décembre 2025. Une routine simple permet de garder une longueur d’avance : consultez régulièrement le changelog, déclenchez des alertes sur les en-têtes d’obsolescence et maintenez des tests de contrat construits à partir des schémas téléchargeables de Walmart, afin qu’une modification fasse échouer un test plutôt que la commande d’un client.

Développer en interne ou confier le projet ?

Le client de jetons et le module d’envoi de flux présentés ci-dessus peuvent être développés en une après-midi. Le temps est surtout consacré à tout ce qui les entoure : faire correspondre votre catalogue à des specs de types de produits qui changent toutes les quelques semaines, réconcilier les statuts de commande pour éviter les doubles expéditions et maintenir une source unique de vérité pour les stocks sur Walmart et tous vos autres canaux de vente.

Développez en interne si Walmart est votre seul canal, si votre catalogue est réduit et si votre équipe peut absorber les changements de spec. Faites-vous accompagner si vous vendez sur plusieurs marketplaces, si votre catalogue correspond de façon inégale aux types de produits Walmart ou si vous ne pouvez pas vous permettre une survente pendant la stabilisation de l’intégration.

Vous souhaitez obtenir une estimation pour une intégration Walmart ou une configuration multicanale qui l’inclut ? Demandez un devis gratuit à Netalith. Le prix est défini selon le périmètre, sans frais de compte ni engagement.