ScreenshotNeo
Sign in Get a free key

BlogGuides

In-Depth Guide to the Walmart API

Learn Walmart API authentication, headers, feeds, throttling, Solution Providers, retries, and production integration patterns with runnable examples.

By the ScreenshotNeo team1 October 20268 min read

The Walmart Marketplace API is a REST API suite for automating catalog, inventory, pricing, orders, fulfillment, reports, advertising, seller insights, and notifications. Most server integrations use OAuth 2.0 client credentials, short-lived access tokens, Walmart’s common headers, and asynchronous feeds for high-volume changes.

This guide covers credential setup, authenticated requests, feed processing, throttling, retries, delegated access through Solution Providers, and production troubleshooting.

1. What the Walmart API covers

Walmart exposes APIs around the main seller workflows:

Area Typical work Common integration choice
Catalog and items Create, maintain, validate, and monitor item data Feeds for bulk changes; direct endpoints for exceptions
Inventory Publish available-to-sell quantities Scheduled feeds or endpoint-specific updates
Pricing and promotions Update prices and promotional data Feeds for routine batches
Orders Read orders and perform shipment, cancellation, or refund operations Authenticated synchronous calls, subject to endpoint limits
Fulfillment Send shipment and fulfillment updates Endpoint-specific calls and status polling
Reports and insights Retrieve operational and seller reports Report endpoints with their own quotas
Advertising and notifications Manage advertising workflows and receive event information Use the API and permissions documented for your market

Choose an API by workflow coverage, whether processing is synchronous or asynchronous, market availability, permission scope, and rate limits. Endpoint versions and required headers can differ by API and market.

2. Credentials, environments, and token lifetime

  1. Create an application in the Walmart Developer Portal and obtain a client ID and client secret. Start in the sandbox when it is available for the API you are implementing.
  2. Store both values in a secret manager or environment variables. Never commit them to source control, logs, browser code, or support tickets.
  3. Request an access token from https://marketplace.walmartapis.com/v3/token.
  4. Use the client_credentials grant for a seller or server integration. Use authorization-code and refresh-token grants only where the specific Walmart application flow documents them.

Walmart access tokens last 15 minutes (900 seconds). Refresh tokens, where issued by the documented flow, last one year (365 days). Treat these durations as operational settings: cache an access token until shortly before expiry, then request a replacement.

Request a token with cURL

#!/usr/bin/env bash
set -euo pipefail

TOKEN=$(curl -sS -u "$WALMART_CLIENT_ID:$WALMART_CLIENT_SECRET" \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'Accept: application/json' \
  -d 'grant_type=client_credentials' \
  https://marketplace.walmartapis.com/v3/token)

echo "$TOKEN"

Request a token with Python

import os
import requests

response = requests.post(
    "https://marketplace.walmartapis.com/v3/token",
    auth=(os.environ["WALMART_CLIENT_ID"], os.environ["WALMART_CLIENT_SECRET"]),
    headers={
        "Content-Type": "application/x-www-form-urlencoded",
        "Accept": "application/json",
    },
    data={"grant_type": "client_credentials"},
    timeout=30,
)
response.raise_for_status()
token = response.json()["access_token"]
print(token)

Request a token with Node.js

const credentials = Buffer.from(
  `${process.env.WALMART_CLIENT_ID}:${process.env.WALMART_CLIENT_SECRET}`
).toString('base64');

const response = await fetch('https://marketplace.walmartapis.com/v3/token', {
  method: 'POST',
  headers: {
    Authorization: `Basic ${credentials}`,
    'Content-Type': 'application/x-www-form-urlencoded',
    Accept: 'application/json'
  },
  body: 'grant_type=client_credentials'
});

if (!response.ok) throw new Error(`${response.status}: ${await response.text()}`);
const token = (await response.json()).access_token;
console.log(token);

3. Build an authenticated Walmart request

Authenticated API calls use the WM_SEC.ACCESS_TOKEN header plus Walmart’s common headers. Global APIs also require WM_MARKET. The exact required set depends on the endpoint and market.

Header Purpose
WM_SEC.ACCESS_TOKEN OAuth access token returned by the Token API
WM_CONSUMER.CHANNEL.TYPE Consumer or channel identifier required by the API
WM_SVC.NAME Name of the Walmart service being called
WM_MARKET Market identifier for global APIs when required
Accept Response media type, commonly JSON
Content-Type Request body media type for POST, PUT, or multipart requests

Reusable request pattern

curl -sS "$WALMART_API_URL" \
  -H "WM_SEC.ACCESS_TOKEN: $WALMART_ACCESS_TOKEN" \
  -H "WM_CONSUMER.CHANNEL.TYPE: $WALMART_CHANNEL_TYPE" \
  -H "WM_SVC.NAME: $WALMART_SERVICE_NAME" \
  -H "WM_MARKET: $WALMART_MARKET" \
  -H 'Accept: application/json'

Set WALMART_API_URL to the exact resource URL from the reference for your market. Do not assume that headers or paths from one API apply to another.

4. Feeds versus single-record endpoints

Use asynchronous feeds for routine, high-volume catalog, price, and inventory work. A feed lets you submit a batch, receive a feed ID, and poll processing status instead of making one request per item.

  1. Build the feed in the JSON or XML schema required by the target API.
  2. Validate locally against Walmart’s current schema before uploading.
  3. Submit the feed as the documented multipart payload.
  4. Persist the returned feed ID with your source batch, market, and submission timestamp.
  5. Poll feed status until the feed reaches a terminal state.
  6. Retrieve line-level errors and reconcile each failed item before retrying.

Reserve single-record updates for urgent corrections, exceptions, or workflows where the endpoint is explicitly designed for synchronous changes. A feed can be accepted while individual lines fail, so a successful submission response is not proof that every item changed.

Feed processing checklist

  • Validate required identifiers, units, and enumerated values.
  • Keep the original payload or a content hash for auditability.
  • Record the feed ID and polling attempts.
  • Separate transient transport failures from line-level validation errors.
  • Retry only failed lines after fixing their data.
  • Make batch generation idempotent in your own system so a retry cannot silently duplicate business actions.

5. Rate limits, 429 responses, and backoff

Limits vary by endpoint and market and are enforced with a token-bucket model. A 429 response means the caller is being throttled. Walmart documents quota examples for the US market including 5,000 requests per minute for all feed statuses, 60 requests per hour for feed error reports, and 60 requests per minute for several ship, refund, and cancel order operations. Check the current endpoint-specific table before setting production concurrency.

Read x-current-token-count and X-Next-Replenishment-Time when present. Honor Retry-After when supplied, then use exponential backoff with jitter.

async function withBackoff(operation, maxAttempts = 6) {
  for (let attempt = 0; attempt < maxAttempts; attempt++) {
    const response = await operation();
    if (response.status !== 429) return response;

    const retryAfter = Number(response.headers.get('retry-after'));
    const serverDelay = Number.isFinite(retryAfter) ? retryAfter * 1000 : 0;
    const exponential = Math.min(60_000, 500 * 2 ** attempt);
    const jitter = Math.floor(Math.random() * 250);
    await new Promise(resolve => setTimeout(resolve, Math.max(serverDelay, exponential) + jitter));
  }
  throw new Error('Walmart API remained throttled after retries');
}

Use separate queues for feeds, polling, and order mutations. Polling too aggressively can consume the quota needed for business-critical operations.

6. Reliability and production design

  • Token cache: Cache tokens per credential and market, with a small expiry safety window. On an authentication failure, invalidate the cache and obtain a new token once.
  • Timeouts: Set finite connect and read timeouts. A timeout does not prove that Walmart did not receive the request; reconcile status before replaying a mutation.
  • Retries: Retry network errors, 408, 429, and documented 5xx conditions with bounded exponential backoff. Do not blindly retry validation errors or unauthorized requests.
  • Idempotency: Use your own operation IDs and durable state transitions. Before repeating a ship, refund, or cancel action, query the current order state when the API allows it.
  • Observability: Log endpoint, market, HTTP status, request correlation data, feed ID, retry count, and latency. Redact tokens, secrets, customer data, and full authorization headers.
  • Schema drift: Keep payload fixtures and contract checks so a schema or enum change is detected before a large feed is submitted.

7. Solution Providers and delegated access

Sellers can authorize approved Solution Providers to access their accounts through delegated access. Treat each provider as a separate integration boundary:

  1. Confirm the provider is currently approved for the required Walmart capability and market.
  2. Use separate seller keys or credentials for each provider.
  3. Grant only the object permissions the integration needs.
  4. Record authorization, token, and credential rotation events.
  5. Revoke access when the relationship ends and review permissions periodically.

Do not describe a commercial partner as approved without checking Walmart’s current provider resources. Approval, market coverage, and permissions can change.

8. Troubleshooting common errors

Symptom Likely cause Fix
401 or invalid token Expired token, malformed Basic credentials, or wrong grant Verify client credentials, request a fresh token, and send it as WM_SEC.ACCESS_TOKEN.
403 forbidden The application or seller authorization lacks the required permission Check delegated access, object scope, market, and application configuration.
400 on token request Wrong content type, missing grant, or invalid Basic header Use form encoding, grant_type=client_credentials, and Basic authentication exactly as documented.
400 on API request Missing market/common header or invalid payload schema Compare every header and field with the endpoint reference; validate the feed before submission.
429 Too Many Requests Endpoint or market quota exceeded Honor Retry-After, inspect quota headers, reduce concurrency, and schedule work through a queue.
Feed accepted but items failed Line-level validation or business-rule errors Poll the feed, download the error report, fix only failed lines, and submit a corrected batch.
Repeated timeout Large payload, slow processing, network issue, or overloaded polling loop Use bounded timeouts, asynchronous feeds, fewer concurrent polls, and status reconciliation before retrying.
Works in one market but not another Different endpoint availability, headers, permissions, or quotas Read the market-specific reference and configure market-aware queues and credentials.

9. Performance and cost considerations

Throughput is usually limited by endpoint quotas and feed processing time rather than raw HTTP bandwidth. Batch routine changes into feeds, poll at a measured interval, and reserve quota for urgent order operations. Track request volume by endpoint and market so a new catalog job cannot starve fulfillment traffic.

Walmart API usage costs depend on your Walmart commercial arrangement and the API program; the operational constraints documented here are request quotas, token lifetimes, payload validation, and processing latency. Budget engineering time for schema validation, retries, reconciliation, and monitoring.

10. Minimal integration plan

  1. Create credentials and test token acquisition in sandbox where supported.
  2. Implement a token cache with expiry handling.
  3. Build one authenticated read request with market-aware headers.
  4. Implement feed submission, status polling, and line-level error storage.
  5. Add quota-aware queues, 429 handling, and bounded retries.
  6. Test authorization failures, expired tokens, malformed payloads, throttling, and partial feed failures.
  7. Move to production with secrets in a manager, structured logs, alerts, and a rollback or reconciliation procedure.

Or skip the browser setup

If you need screenshots of Walmart pages for documentation, QA, or an internal catalog workflow, ScreenshotNeo provides a single website screenshot API call. It removes cookie banners, newsletter popups, and chat widgets before capture. Bot checks, blank pages, failed loads, timeouts, and cache hits are not billed, and response headers identify the page verdict and billing status. An MCP server lets Claude, Cursor, and other MCP clients call take_screenshot, get_page_info, and capture_pdf.

cURL

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

Python

import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)

Node.js

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

See the ScreenshotNeo API documentation for the available capture options. The Free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000. Create a free ScreenshotNeo account.

FAQ

How often must I request a Walmart access token?

Access tokens last 15 minutes. Cache and reuse them until shortly before expiry instead of requesting one for every API call.

Should every catalog update be a feed?

Use feeds for routine high-volume catalog, price, and inventory changes. Use direct endpoints for urgent or exceptional updates when the endpoint supports them.

What should my client do after a 429?

Honor Retry-After when present, inspect quota headers, reduce concurrency, and retry with bounded exponential backoff and jitter.

Can a Solution Provider use one credential for all sellers?

Delegated access uses separate seller authorizations and credentials or permissions. Keep each seller and provider boundary isolated.

Why can a feed succeed while an item fails?

Feed acceptance and line processing are separate outcomes. Always poll the feed and inspect line-level errors before marking the batch complete.

Keep reading

7 min read

LinkedIn Open to Work Image

Learn what LinkedIn’s Open to Work photo frame means, who can see it, how to add or remove it, and how to choose the right privacy setting.