Walmart Marketplace API Integration: 2026 Developer Guide

What the Walmart Marketplace API covers

The Walmart Marketplace API is a set of REST endpoints on marketplace.walmartapis.com that lets a seller, or an approved Solution Provider acting for sellers, manage items, inventory, prices, orders, returns, reports and notifications on Walmart.com without opening Seller Center. This guide covers the US Marketplace developer portal; the Canada, Mexico and Chile portals are separate.

A working integration has four moving parts. The order below is the order to build them in, and it differs slightly from the order Walmart's overview lists them.

Orders come before inventory on purpose. The moment you push a positive quantity for a live item, orders can arrive. An integration that can list and stock items but cannot yet acknowledge and ship orders is an oversell waiting to happen, so keep quantities at zero until the order path works end to end. Reports, insights, advertising, returns and Walmart Fulfillment Services (WFS) are add-ons you can defer.

Direct integration or approved Solution Provider?

Your path depends on whose Walmart account the code talks to. The decision changes your credentials, your authorization flow and even your rate limits.

Walmart's docs say new Solution Providers must use OAuth 2.0, not the older delegated access model. Rate limits are allotted per seller, and a seller's direct calls and an approved Solution Provider app's calls are counted separately. If one provider ships several apps, each app gets its own allotment.

If Walmart is one of several channels you need to keep in sync, our marketplace integration service covers Walmart alongside Amazon SP-API, eBay, Etsy, Temu, Shein and Shopee, including listings, inventory, orders and tracking.

Walmart Marketplace API authentication (OAuth 2.0)

Every Marketplace API call carries an OAuth 2.0 access token in the WM_SEC.ACCESS_TOKEN header, plus WM_SVC.NAME set to Walmart Marketplace. The token comes from the Token API at https://marketplace.walmartapis.com/v3/token and lives for 15 minutes; the response reports expires_in as 900 seconds. The Token API supports three grant types: client credentials, authorization code and refresh token.

The Client ID and Client Secret are not the old Consumer ID and Private Key. The old method required you to sign each request; OAuth removes the signature and cuts the number of headers. The portal keeps separate Production Keys and Sandbox Keys, and you can view a secret again whenever you need it.

The client that follows caches the token and refreshes it a minute early. Check the header names and the token request against the Token API reference before shipping, because this sketch was written from the documentation rather than run against a live seller account.

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',
        }

Where authentication integrations usually go wrong

• One token per request. With 15-minute tokens it is tempting to fetch a fresh one for every job. Cache it, and if you run several workers, share the cache or guard the refresh with a lock so ten workers do not refresh at the same second.
• Stale code samples. At least one bulk inventory guide still shows a Basic Authorization header built from a consumer key and secret. OAuth is what the docs require now, so treat any sample that signs requests or uses Consumer ID as legacy.
• Unlimited 401 retries. On a 401, invalidate the token and retry once. A second 401 means bad credentials, wrong environment (sandbox key against production) or insufficient scope, and looping will not fix it.
• Scope surprises. OAuth attaches a scope to each set of credentials, and Walmart rejects calls outside it. Seller credentials get full access; credentials issued with a narrower scope are rejected on calls outside it.

Walmart API rate limits and 429 errors

Walmart enforces limits in two ways: a request rate per API, which returns 429 Too Many Requests when exceeded, and a maximum file size per feed type, which returns 413 Payload Too Large. Limits use a token bucket. Each call spends a token and the bucket refills at a fixed rate, so a limit of 20 requests per hour may refill one request every 3 minutes rather than resetting on the hour.

Every response carries your remaining budget for that API in the x-current-token-count header, along with the time the count next increases. The two documentation pages spell that second header differently (X-Next-Replenishment-Time on the rate limit page, x-next-replenish-time in the FAQ), so read both spellings and log what you actually receive.

These are default limits published for individuals and smaller businesses, taken from Walmart's rate limiting page. Check the page for the full table, because it also covers WFS, insights, reports and advertising endpoints.

How to design around the limits

• Budget per seller, not per process. Limits belong to the seller account, so a multi-tenant integration needs one bucket per connected seller. A single global throttle either starves small sellers or lets one large seller drain the rest.
• Cache the spec. Get item spec allows 10 calls per minute. Fetch each spec version once, store it, and validate feed payloads locally before you spend a feed submission on them.
• Poll feeds cheaply, fetch error reports sparingly. Status polling has generous headroom at 5000 per minute; the error report at 60 per hour does not. Download it only when a status shows line-item errors.
• Back off with jitter on 429. Exponential delay plus a random component keeps a fleet of workers from retrying in lockstep.

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

Item setup with feeds and item spec 5.0

New items and item updates go through the Bulk Item Setup API, which is a feed endpoint: you POST to /v3/feeds with a feedType query parameter and receive a feed ID. One request can carry up to 10,000 items. Walmart recommends keeping the file under 25 MB for good processing time, with 50 MB allowed for the automotive fitment feeds (FITMENT_ACES and FITMENT_PIES). You can send the file as an attachment or put the JSON payload in the request body.

Item content is validated against an item spec, and the spec moves quickly. Walmart published a new 5.0 build on May 14, 2026, another on June 22, 2026, and on July 28, 2026 it announced a new recommended version, according to Walmart's July 2026 item spec notice. That is three releases in under twelve weeks, each applying to MP_ITEM, MP_MAINTENANCE, MP_WFS_ITEM and OMNI_WFS.

Two practical consequences follow. First, never hard-code a spec version string; read the recommended version from the Item spec reporting and version table, pull the matching schema, and store the version alongside every feed you submit so a rejection can be traced to a spec change. Second, the July build added an item_assortment_type attribute for Collectibles across 20 more product types, and only sellers approved for the Collectibles program may send collectible-specific fields. A catalog mapper that fills every optional attribute it can find will get non-approved sellers rejected.

A feed is accepted before it is applied

A successful response to the POST means Walmart received the file, not that your items are live. The outcome arrives later, at line-item level, from the Feed Status API. Build the loop as submit, store the feed ID, poll status, then act on per-item results: mark items published, queue fixes for failures, and only then fetch the error report. Retrying the whole feed because three lines failed burns a submission and re-sends the 9,997 lines that were fine.

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']

Syncing inventory and price with the Walmart API

Inventory has three entry points, and choosing between them is mostly a question of volume and urgency.

The bulk feed accepts JSON in spec 1.5 (multi-node) or 1.4 (single node), and XML in spec 1.4. Like item feeds, it returns a feed ID and reports line-item results through the Feed Status API.

For pricing, Walmart now offers a pricing and promotions management API with a bulk option, and lists the older Price management API as deprecated. Build on the new one. The PRICE_AND_PROMOTION feed is limited to 10 requests per hour, which is the number to design around: a price feed is a batch you plan, not something you fire on every change.

A sync pattern that survives the limits

• Keep an outbox of changes, not a schedule of full pushes. Record each inventory or price change as a row, coalesce multiple changes to the same SKU, then flush.
• Split traffic by urgency. Send low-stock and out-of-stock changes through single calls at up to 200 per minute; send everything else in batched feeds. A quantity of two changing to zero is not something to leave waiting in a queue.
• Reconcile on a slower cycle. Run a full feed on a schedule to correct drift, and treat it as a repair pass, not the primary sync.
• Listen for Walmart's view. Webhook events such as inventory out of stock, offer published and offer unpublished tell you what Walmart thinks the state is, which is often where a mismatch first shows up.

Retrieving, acknowledging and shipping Walmart orders

Every order line moves through a small set of statuses: Created (placed and ready to acknowledge), Acknowledged (you have confirmed and plan to fulfill), Shipped (marked shipped with tracking), Canceled, and Delivered. The working loop is to retrieve released orders, acknowledge each one, ship it with a carrier and tracking number, and handle cancellations and refunds when they occur.

You can learn about new orders by polling the order endpoints or by subscribing to webhook events. Walmart offers events for purchase order created, purchase order line auto-canceled and order intent to cancel, among others. Subscription creation is allowed 200 times per minute at default limits.

Order handling rules that prevent duplicate shipments

• Assume at-least-once delivery. If you use both webhooks and polling, the same purchase order will arrive twice. Key your records on the purchase order ID and line number, and make acknowledge and ship operations safe to repeat.
• Keep polling as the backstop. A webhook you never received is invisible. A periodic poll of released orders closes that gap at low cost.
• Ship per line. The ship endpoint works on order lines and is limited to 60 calls per minute, so batch a multi-line order into one call instead of one per line.
• Send real carrier and tracking data. Walmart publishes a list of supported carrier names, and it exposes seller performance metrics such as valid tracking rate and on-time shipment through its Insights APIs. Map your carriers to Walmart's names explicitly rather than passing free text.
• Mind the charge structure. Order lines carry PRODUCT and SHIPPING charges, and a SHIPPING charge must include shipDateTime in UTC. Convert timestamps at the boundary and store them in UTC internally.

Walmart also documents a Multi-Line Multi-Quantity (MLMQ) migration guide. If you are reading old integration code or a third-party library, check whether it assumes one line and one quantity per order.

Testing in the Walmart sandbox before go-live

Walmart provides two sandboxes. The static sandbox gives you sandbox credentials, guidance for testing the Marketplace APIs, feed validations and its own throttling limits page. The dynamic sandbox comes with recipes for validating order fulfillment, returns and refunds, and non-WFS inventory. Sandbox keys are issued separately from production keys on the Developer Portal.

Sandbox has its own throttling limits, so a clean run there says little about how much headroom you have in production. Use the sandbox to prove correctness, and use the rate limit page to plan capacity.

Before switching to production, deliberately test the failures, not just the happy path:

1. Let a token expire mid-run and confirm the client refreshes once and continues.
2. Force a 429 and check that backoff engages and the remaining-budget headers are logged.
3. Submit a feed where some lines are valid and some are not, and confirm only the failed lines are queued for repair.
4. Deliver the same order twice, through webhook and poll, and confirm one acknowledgment and one shipment.
5. Feed the parser a response with an extra field and an unknown enum value, and confirm it does not crash.

Keeping a Walmart integration alive: deprecations and the changelog

Walmart published a Marketplace API Deprecation Guide on March 11, 2026. It defines Legacy (still supported but not recommended for new integrations), Deprecated (scheduled for removal, with a published deprecation date and sunset date) and Sunset stages, alongside fully supported Active APIs. Status is published in the documentation and communicated through API response headers, so an integration that logs response headers can be warned by the API itself.

There is also a centralized US API changelog, introduced in April 2025. Entries list added or removed APIs, parameters, response properties and enum values, and properties that change between required and optional. Recent entries, such as the July 23, 2026 release, mostly add optional request and response fields. That is the normal shape of change, and it argues for tolerant parsing: ignore fields you do not know, and never treat an unknown enum value as a fatal error.

Deprecations do land on real endpoints. The developer portal navigation currently marks the older Price management API and the Simplified Shipping Settings API as deprecated, and an earlier Price Incentives change replaced the CPpreference endpoint with a new one, with the old endpoint scheduled for sunset after December 30, 2025. A short routine keeps you ahead of this: review the changelog on a regular schedule, alert on deprecation headers, and keep contract tests built from Walmart's downloadable schemas so a change fails a test instead of a customer's order.

Build it yourself or hand it over?

The token client and the feed submitter above are an afternoon of work. What takes the time is everything around them: mapping your catalog onto product-type specs that change every few weeks, reconciling order states so nothing ships twice, and keeping one truth for stock across Walmart and every other channel you sell on.

Build in-house if Walmart is your only channel, your catalog is small and your team can absorb spec changes. Bring in help if you sell on several marketplaces, your catalog maps unevenly onto Walmart's product types, or you cannot afford an oversell while the integration settles.

If you want an estimate for a Walmart integration, or a multichannel setup that includes it, request a free quote from Netalith. It is priced to scope, and there is no account or commitment involved.