# Walmart > Walmart operates one of the largest first-party commerce API programs in retail. The public, contract-bearing surface is the > seller and supplier platform: Walmart Marketplace (third-party sellers), Dropship Vendor / DSV (1P suppliers), Walmart > Fulfillment Services and Multichannel Solutions (WFS/MCS), Ship With Walmart, and the Marketplace advertising APIs. There is > no public consumer shopping API. Access requires an approved seller, supplier or Solution Provider account; the OpenAPI > definitions, error catalogue, rate limits and changelog are all public and readable without an account. Generated by API Evangelist from https://github.com/api-evangelist/walmart on 2026-08-27. Walmart itself publishes no llms.txt (https://developer.walmart.com/llms.txt returned HTTP 404 on 2026-08-27). ## Base URLs - Marketplace production: https://marketplace.walmartapis.com - 1P Supplier / DSV production: https://api-gateway.walmart.com - Sandbox (all programs): https://sandbox.walmartapis.com - Developer portal: https://developer.walmart.com ## Authentication - OAuth 2.0 client credentials. POST /v3/token with `Authorization: Basic base64(clientId:clientSecret)` and `grant_type=client_credentials`. - Carry the returned token in the **WM_SEC.ACCESS_TOKEN** header — NOT `Authorization: Bearer`. This is the single most common integration mistake. - Also required on every call: `WM_QOS.CORRELATION_ID` (a UUID you generate) and `WM_SVC.NAME`. - Inspect a token with GET /v3/token/detail. - There are no OAuth scopes. Access is granted per object category (Items, Orders, ...) on the credential itself. - Delegated Access keys are being retired: new issuance stopped 2026-07-30 and existing keys stop working end of September 2026. Solution Providers migrate to OAuth 2.0 seller authorization through the Walmart App Store. - Docs: https://developer.walmart.com/us-marketplace/docs/oauth-authentication ## Rate limits - Token-bucket, allotted **per seller**. A seller's direct integration and each approved Solution Provider application get separate buckets. - 202 published per-operation limits, ranging from 1/min (most Insights performance metrics) to 5000/min (GET /v3/orders, GET /v3/feeds). - Response headers: `x-current-token-count` (tokens left for THIS API) and `X-Next-Replenishment-Time` (when the bucket refills). There is no `RateLimit-*` or `Retry-After` header. - Exhaustion returns **429**. An oversized feed file returns **413**. - Docs: https://developer.walmart.com/us-marketplace/docs/rate-limiting ## Errors - Envelope is proprietary, not RFC 9457: `{"errors":[{"code","message","category","severity","field"}]}`. Gateway rejections use the singular `{"error":[{...}]}` form and can be application/xml. - Key codes: INVALID_REQUEST (400), MISSING_REQUEST_HEADER (400), UNAUTHORIZED (401), FORBIDDEN.GMP_GATEWAY_API (403), CONTENT_NOT_FOUND (404), RESOURCE_IS_LOCKED.GMP_RECEIVER_API (423), REQUEST_THRESHOLD_VIOLATED (429), DOWNSTREAM_SYSTEM_TIME_OUT (504). - Docs: https://developer.walmart.com/us-marketplace/docs/error-codes ## What an agent must know before writing - **There is no idempotency mechanism.** No Idempotency-Key header, no request-replay semantics, nowhere on the portal. A retried POST can double-fire. Read state back (GET the order/item) before retrying a write. - **Bulk writes are asynchronous.** POST /v3/feeds returns a feedId; poll GET /v3/feeds/{feedId} at 15 min, 1 h, 2 h, then every 4 h. Errors come from GET /v3/feeds/{feedId}/errorReport. - **Reversibility is state-bounded, not clock-bounded.** Cancel an order only while it is neither shipped nor cancelled; refund only within the remaining allowable amount after prior partial refunds — Walmart states no refund day-window, so do not assume one. Orders auto-cancel if not shipped within 30 days of creation. - **Pagination has two styles.** Offset (`page`, `limit`, default 100) and cursor (`nextCursor`, send `*` first, expires after 2 minutes). ## APIs - Orders — GET /v3/orders, GET /v3/orders/{purchaseOrderId}, POST .../acknowledge, /shipping, /cancel, /refund - Items — GET /v3/items, GET /v3/items/{id}, POST /v3/items/spec, POST /v3/items/catalog/search, DELETE /v3/items/{sku} - Inventory — GET/PUT /v3/inventory, GET/PUT /v3/inventories/{sku} (per ship node) - Prices — PUT /v3/price, repricer strategies under /v3/repricer, price incentives under /v3/price/incentives - Promotions — PUT /v3/price (promotional), GET /v3/promo/sku/{sku} - Feeds — POST /v3/feeds?feedType=..., GET /v3/feeds, GET /v3/feeds/{feedId}, GET /v3/feeds/{feedId}/errorReport - Returns & Refunds — GET /v3/returns, POST /v3/returns/{returnOrderId}/refund - Fulfillment (WFS/MCS) — /v3/fulfillment/orders-fulfillments, /return-orders, /inbound-shipments, v4 booking + label surface - Ship With Walmart — /v3/shipping/labels (create, estimate, download, discard, scan form) - Settings — /v3/settings/shipping (templates, ship nodes, account), /v3/settings/partnerprofile - Insights — /v3/insights/performance/* (VTR, OTD, cancellations, returns), /v3/insights/items/* - Notifications (webhooks) — /v3/webhooks/subscriptions, /v3/webhooks/eventTypes, /v3/webhooks/test - On-Request Reports — /v3/reports/reportRequests, /v3/reports/schedules, /v3/reports/downloadReport - Rules — /v3/rules, /v3/rules/exceptions - Utilities — GET /v3/utilities/apiStatus, GET /v3/utilities/taxonomy - Advertising (SEM) — /v3/advertising/sem/campaigns, /items, /billing-history - Assortment Recommendations — /v3/growth/assortment/recommendations - Reviews Acceleration — /v3/growth/reviews-accelerator - DSV (1P) — cost, inventory, items, lag time, orders, on-request reports, pre-generated reports on api-gateway.walmart.com ## Events (webhooks) Register an HTTPS destination with POST /v3/webhooks/subscriptions. Thirteen event types: OFFER_PUBLISHED, OFFER_UNPUBLISHED, BUY_BOX_CHANGED, INVENTORY_OOS, PO_CREATED, PO_LINE_AUTOCANCELLED, ORDER_INTENT_TO_CANCEL, ORDER_MANAGEMENT_EVENT, DRIVER_STATUS_NOTIFICATION, RETURN_NOTIFICATIONS, REPORT_STATUS, ASSORTMENT_RECOMMENDATIONS, SELLER_PERFORMANCE_NOTIFICATIONS. Envelope: eventType, eventVersion, eventTime, eventId, payload. Walmart publishes no AsyncAPI document for this surface. ## MCP Walmart runs a remote MCP server at **https://developer.walmart.com/mcp** (JSON-RPC over HTTP). It is OAuth 2.1 gated — authorization-code + PKCE S256, dynamic client registration at https://developer.walmart.com/oauth/register, required scopes `openapi_read` and `offline_access`. Metadata: /.well-known/oauth-authorization-server and /.well-known/oauth-protected-resource. The scope indicates it serves the portal's API documentation, not the Marketplace runtime. An anonymous tools/list returns JSON-RPC error -32001 "Authentication required", so the tool list is not public. ## Lifecycle - Versioning is by URI path (/v3/, /v4/ on newer WFS inbound-shipment endpoints). The Item Spec has its own version stream (currently 5.0) with dated update pages. - Four published lifecycle states — Active, Legacy, Deprecated, Sunset — each with a stated support policy, and a public table of every non-Active API with its migration path, status date and sunset date. - Deprecation guide: https://developer.walmart.com/us-marketplace/docs/walmart-marketplace-api-deprecation-guide - Status: https://developer.walmart.com/api-status and GET /v3/utilities/apiStatus - Changelog: https://developer.walmart.com/us-marketplace/changelog (51 entries, roughly weekly) ## SDKs Walmart publishes no maintained first-party client library on any package registry. The two first-party repos (walmartlabs/partnerapi_sdk_dotnet, walmartlabs/walmart-api) are archived and last touched in 2020 and 2019. Walmart's own guidance is to generate a client from the OpenAPI with OpenAPI Generator; a Java recipe is published at https://developer.walmart.com/us-marketplace/page/new-mcs-java-openapi-client-integration-guide ## Sandbox https://sandbox.walmartapis.com with its own credential pair from https://developer.walmart.com/generateKey. Dynamic sandbox with a Simulations API for driving state transitions, plus three published recipes (order fulfillment, returns and refunds, inventory reservations/decrements/stockouts) with cURL, Python and Java samples. Sandbox feed limits are 30/hour with 2 KB to 100 KB file caps. No test cards or magic identifiers are published. ## Identifiers GS1 GTIN-14 is a first-class item identifier declared in the contract (`gtin` parameter in 10 of 27 specs), alongside UPC, EAN and ISBN and the seller's own SKU. Walmart also exposes a GTIN Exemption API at GET /v3/items/gtin-exemption/status. ## Links - Developer portal: https://developer.walmart.com/ - US Marketplace docs: https://developer.walmart.com/us-marketplace/docs/introduction-to-marketplace-apis - API reference: https://developer.walmart.com/us-marketplace/reference/getallorders-1 - Getting started: https://developer.walmart.com/us-marketplace/page/getting-started - Postman collections: https://developer.walmart.com/us-marketplace/page/walmart-api-postman-collection - Support: https://developer.walmart.com/us-marketplace/docs/troubleshooting-and-support - Terms: https://developer.walmart.com/us-marketplace/page/terms-and-conditions - Security disclosure: https://corporate.walmart.com/article/responsible-disclosure-policy