Walmart APIs SDK

The Walmart APIs SDK for Python provides access to the Walmart APIs REST APIs from Python applications.

OAuth token issuance for Walmart Marketplace, covering both v4 authorization flows in one contract:

1. Seller-direct (client_credentials) — a seller's own application exchanges its client credentials for a short-lived access token, then calls the v4 APIs with Authorization: Bearer <token>.
2. Solution-Provider delegated (authorization_code + PKCE, refresh_token, and Dynamic Client Registration) — a seller grants a Solution Provider's application access to their Marketplace account.

Both flows are served by the Authorization API as a stateless proxy to Walmart IAM : IAM remains the sole issuer; no secrets are stored and no tokens are signed here. Access tokens are opaque, Bearer-type, short-lived; refresh tokens (delegated flow) are rotated on use. Never log tokens.

One token endpoint, grant dispatch

POST /auth/v4/token handles all three grants (client_credentials, authorization_code, refresh_token) via grant_type dispatch — the merged v4 contract ( for seller-direct, for delegated). This is why the two formerly separate specs (openapi.yaml + delegated-oauth.yaml) are now a single document: a path can carry exactly one post:, so one file makes the shared endpoint unambiguous for codegen and for the implementing controller.

Posture

• Seller-direct is OAuth 2.0 : documents what IAM/Apigee already do. IAM cannot add new auth features for this flow, so client_credentials issues no refresh token, scope= is accepted-but-ignored (no down-scoping), and introspection (RFC 7662) / revocation (RFC 7009) / discovery (RFC 8414) are deliberately absent.
• Delegated is OAuth 2.1 : IAM already supports PKCE (S256), refresh rotation (~1-year TTL via offline_access), and Dynamic Client Registration (RFC 7591), so this flow specifies them properly.

The one modernization over /v3 shared by both flows is the access-token header: v4 uses the standard Authorization: Bearer and does not use WM_SEC.ACCESS_TOKEN (the gateway already tolerates Bearer).

Delegated-flow upstream gaps (, pending)

GET /auth/v4/authorize documents the OAuth-2.1-correct target. Three of its guarantees depend on upstream changes that are not yet in place: iss emission (RFC 9207), exact redirect_uri enforcement, and server-side PKCE S256 enforcement (rejecting plain) are IAM / app-store responsibilities tracked in . the Authorization API validates the request-side invariants it can and redirects correctly; the full end-to-end guarantee lands when IAM + app-store ship those changes.

Pod Owner: Pod 0 — Core & Auth Implementation target: the Authorization API (proxy) → Walmart IAM , Retrieve catalog and product information from the Walmart Marketplace catalog.

Pod Owner: Pod 1 — Items & Catalog Implementation target: Partner Item Query Service (PIQS), Submit analytics queries and retrieve structured data from Walmart's data platform. Modeled after Walmart Seller API Data Kiosk API.

ADR pending: GraphQL vs REST query language — see docs/adr/ once filed. Until the ADR resolves, the query body is treated as an opaque string.

Pod Owner: Pod 4 — Feeds & Reports Implementation target: Walmart Analytics / Data Platform, Submit bulk data to Walmart Marketplace via asynchronous feed processing. Sellers submit a feed file in a single API call; the server handles document storage and initiates async processing. Poll feed status with the feedId returned in the submission response.

Pod Owner: Pod 4 — Feeds & Reports Implementation target: Walmart Feed Service / Bulk Operations

, WFS Inbound Plans API. Walmart Seller API — Fulfillment Inbound contract.

Terminology: WFS = Walmart Fulfillment Services, Ship Node = fulfillment center., WFS Inbound Delivery Windows, Self-Ship Appointments & Operation Status API. Walmart Seller API — Fulfillment Inbound contract. Terminology: WFS = Walmart Fulfillment Services, Ship Node = fulfillment center., WFS Inbound Packing. Walmart Seller API — Fulfillment Inbound contract. Terminology: WFS = Walmart Fulfillment Services, Ship Node = fulfillment center., WFS Inbound Packing & Placement API. Walmart Seller API — Fulfillment Inbound contract. Terminology: WFS = Walmart Fulfillment Services, Ship Node = fulfillment center., WFS Inbound Items, Compliance, Labels & Prep API. Walmart Seller API — Fulfillment Inbound contract. Terminology: WFS = Walmart Fulfillment Services, Ship Node = fulfillment center., WFS Inbound Shipments API. Walmart Seller API — Fulfillment Inbound contract. Terminology: WFS = Walmart Fulfillment Services, Ship Node = fulfillment center., Create and manage WFS (Walmart Fulfillment Services) outbound fulfillment orders. Sellers ship inventory to Walmart ship nodes; Walmart picks, packs, and ships to end customers.

Pod Owner: Pod 2 — Orders & Fulfillment Implementation target: WFS Outbound / Ship Node Service, Manage seller inventory on the Walmart Marketplace.

Pod Owner: Pod 3 — Inventory & Pricing Implementation target: Walmart Inventory Service, Create, fully update, patch, and delete listings items for sellers on the Walmart Marketplace. Modeled after Walmart Seller API Listings Items API.

Pod Owner: Pod 1 — Items & Catalog Implementation target: Walmart Item Setup Service, Get information about listing restrictions on items in the Walmart Marketplace. Identifies compliance blocks, category restrictions, and approval requirements.

Pod Owner: Pod 3 — Inventory & Pricing Implementation target: Walmart Item Compliance / Restriction Service, SUPERSEDED — NOT SCHEDULED FOR IMPLEMENTATION. the Merchant Fulfillment API is obsolete: its operations are covered by the Shipping API, and both front the same upstream (Ship With Walmart). Per Suresh's SWW-consolidation analysis, every operation below is marked counts toward Pod 2 implementation scope. This spec is retained for reference only (tombstone) — no code is being built against it. New seller-fulfilled shipping work goes to the Shipping API.

Tracking: (this deprecation). The one partial-coverage gap (MFN full-record getShipment has no single the Shipping API equivalent) is owned by Suresh for decision in .

---

Get eligible shipping services and purchase shipping labels for seller-fulfilled orders. Modeled after Walmart Seller API Merchant Fulfillment API.

Pod Owner: Pod 2 — Orders & Fulfillment Implementation target: Ship With Walmart (SWW) — SWW-LABEL-SERVICE (internal /v3/sww/labels/* synchronous REST; see docs/mapper/mfn-mapper-feasibility.md), Retrieve and manage Walmart Marketplace orders.

Pod Owner: Pod 2 — Orders & Fulfillment Implementation target: Walmart Order Management Service (OMS)

, Unified Payments domain API for Walmart Marketplace sellers.

Consolidates Pod 5 (Finances / financial event reporting) and Pod 6 (Outbound Payments — settlement, reconciliation, payout execution) into a single service under the Payments domain .

Category A (7 routes): Reporting — delegated to mp-payment-reporting upstream. Category B (9 routes): Execution — delegated to GMPPayments upstream. Finances (4 routes): Financial event reporting — delegated to GMP partnerTxnSearch and commission endpoints (, ).

Routes with x-walmart-pii: true contain order/seller PII and require an RDT issued by the Tokens service (Pod 0, ) in production.

Domain Owner: Payments Domain (consolidated Pod 5 + Pod 6) Tech Lead: @cssehga Replaces: the payments settlement backend (v3 BFF); the Payments API (Pod 5), Pricing information for seller items and competitive pricing summaries. Aligned to SP-API productPricingV0 surface (April 2026 release), with Walmart Item ID substituted for ASIN as the primary item identifier .

Three GET endpoints are backed by IQS / GCI catalog_index . Five batch/item endpoints are Phase 1 stubs pending implementation — through .

Pod Owner: Pod 3 — Inventory & Pricing Implementation target: Walmart Price Service / Competitive Intelligence, Fee estimate endpoints for seller items. Aligned to SP-API productFeesV0 surface, with Walmart Item ID substituted for ASIN as the primary item identifier , and Amazon-specific branding replaced with Walmart equivalents.

All three endpoints are Phase 2 implementations backed by:

• IQS catalog_index — item enrichment (category, weight, dims, GTIN)
• Partner Rate Service (Columbus) — referral fee by category
• WFS Fulfillment Fee Service (payment-app.wfs) — WFS pick-and-pack fees

Pod Owner: Pod 3 — Inventory & Pricing, Retrieve Walmart product type definitions, attribute schemas, and item classification rules used when setting up seller listings.

Pod Owner: Pod 1 — Items & Catalog Implementation target: Walmart Item Classification Service, Create, cancel, and retrieve seller reports. Supports scheduled and on-demand reports with async processing.

Pod Owner: Pod 4 — Feeds & Reports Implementation target: Walmart Seller Reporting Service, Retrieve information about a seller's Walmart Marketplace account and marketplace participations.

Pod Owner: Pod 5 — Seller & Finances Implementation target: Walmart Seller Account Service / Seller Center, Shipping API for sellers to request rates, purchase shipping labels, track shipments, and manage delivery exceptions across Walmart Marketplace and WFS channels.

Surface aligned with industry SP-API Shipping v2. Pod 2 — Orders & Fulfillment owns this service. Common types (Address, Money, Weight, PackageDimensions) are inlined per Pod 2 convention, byte-identical to the canonical copies in the Merchant Fulfillment API; (proposed) defines the future promotion path to models/_shared/ once the Rule of Three triggers a coordinated extraction PR., Create upload destinations (pre-signed URLs) for feed documents and retrieve previously uploaded documents. Used in conjunction with the Feeds service for async bulk operations.

Pre-signed URLs must not appear in logs — treat as secrets.

Pod Owner: Pod 4 — Feeds & Reports Implementation target: Walmart Document Store / S3 pre-signed URLs

---

Installation

To install the Python SDK from PyPI, with whichever package manager your project uses:

pip install apimatic-wm-v4-sdk

uv add apimatic-wm-v4-sdk

poetry add apimatic-wm-v4-sdk

To install from the SDK source instead, give the tool a path containing a slash — a bare folder name is looked up on PyPI, and resolves to whatever project holds that name there:

pip install <path-to-sdk>

---

Quick Start

Synchronous client

Construct WalmartApisClient with keyword arguments, and call close() when you are done. Every argument is optional; the full list is in the SDK map.

from walmart_apis import WalmartApisClient
from walmart_apis.auth import SellerAuthAuthorizationCodeScope, SellerAuthClientCredentialsScope, WalletAuthScope
from walmart_apis.core import AuthorizationCodeCredentials, BasicAuthCredentials, ClientCredentials


def prompt(url: str) -> str:
    return input(f"Open {url}, then paste the code: ")


client = WalmartApisClient(
    seller_auth_authorization_code=AuthorizationCodeCredentials[SellerAuthAuthorizationCodeScope](
        client_id="YOUR_CLIENT_ID", redirect_uri="YOUR_REDIRECT_URI", prompt_for_authorization_code=prompt
    ),
    seller_auth_client_credentials=ClientCredentials[SellerAuthClientCredentialsScope](
        client_id="YOUR_CLIENT_ID", client_secret="YOUR_CLIENT_SECRET"
    ),
    basic_client_auth=BasicAuthCredentials(username="YOUR_USERNAME", password="YOUR_PASSWORD"),
    wallet_auth=ClientCredentials[WalletAuthScope](client_id="YOUR_CLIENT_ID", client_secret="YOUR_CLIENT_SECRET"),
    environment="production",
)

# TODO: call endpoints here -- see api-reference.md

client.close()

Alternatively, scope it -- with WalmartApisClient(...) as client: closes the pool on exit; see Best Practices.

Client is exported as an alias of WalmartApisClient, so from walmart_apis import Client also works.

The SDK accepts every model-typed input in two interchangeable spellings, both type-checked: the typed model, or a plain dict with the same keys -- the OrDict and Model | ModelDict unions in the SDK map. Pick whichever suits the call site: the dict form needs no import, while the model form adds a keyword-checked constructor and editor completion.

Asynchronous client

AsyncWalmartApisClient mirrors WalmartApisClient with identical method names, and every endpoint method is a coroutine. It takes the same arguments, with some differences -- for example, the transport argument is custom_async_http_client.

from asyncio import run, to_thread

from walmart_apis import AsyncWalmartApisClient
from walmart_apis.auth import SellerAuthAuthorizationCodeScope, SellerAuthClientCredentialsScope, WalletAuthScope
from walmart_apis.core import AsyncAuthorizationCodeCredentials, BasicAuthCredentials, ClientCredentials


async def prompt(url: str) -> str:
    print(f"Open {url}")
    return await to_thread(input, "Paste the code: ")


async def main() -> None:
    client = AsyncWalmartApisClient(
        seller_auth_authorization_code=AsyncAuthorizationCodeCredentials[SellerAuthAuthorizationCodeScope](
            client_id="YOUR_CLIENT_ID", redirect_uri="YOUR_REDIRECT_URI", prompt_for_authorization_code=prompt
        ),
        seller_auth_client_credentials=ClientCredentials[SellerAuthClientCredentialsScope](
            client_id="YOUR_CLIENT_ID", client_secret="YOUR_CLIENT_SECRET"
        ),
        basic_client_auth=BasicAuthCredentials(username="YOUR_USERNAME", password="YOUR_PASSWORD"),
        wallet_auth=ClientCredentials[WalletAuthScope](client_id="YOUR_CLIENT_ID", client_secret="YOUR_CLIENT_SECRET"),
        environment="production",
    )
    # TODO: call endpoints here, awaiting each -- see api-reference.md
    await client.aclose()


run(main())

Alternatively, scope it -- async with AsyncWalmartApisClient(...) as client: closes the pool on exit. Only the async spelling is aclose, matching httpx2; see Best Practices.

AsyncClient is the exported alias. Each client accepts only its own transport argument and its own prompt flavour; passing the other's is a TypeError at runtime and an error under mypy.

---

Usage

Two generated references cover the SDK; each answers a different question:

Reference	For
API Reference	Usage guidance for a single parsed operation: client.<group>.<operation>(...) returns the typed payload and raises ApiError on any non-2xx, with .error the typed error body, or RawError for a status the operation does not document.
Raw API Reference	The same for the raw variant: client.<group>.with_raw_response.<operation>(...) returns ApiResult[T, E] and never raises for an API error.

Both API references carry every one of the 174 operations, with a sync and an async sample and a parameter table each.

SDK map

This SDK ships a generated SDK map -- sdk-map.md -- a deterministic, lookup-oriented table of contents of the SDK's Python surface, generated by APIMatic alongside this SDK.

Consult the map before scanning or grepping the source: it answers call-level contract questions by lookup, and for anything it does not carry -- model shapes, enum values, an endpoint's route or behavioural prose -- it names the one source file to read. How to read the map itself, including the SDK-wide defaults its rows rely on, is stated at the top of sdk-map.md.

Best Practices

Match the disposal to the client's lifetime: an application-lifetime client is closed once at shutdown with close() / aclose(); where the lifetime fits a block, with WalmartApisClient() as client: / async with AsyncWalmartApisClient() as client: releases it automatically. Both are idempotent, but a closed client is not reusable: the next call raises. The client closes whatever transport it holds, including one you supplied via custom_http_client / custom_async_http_client; if you intend to reuse your own transport across clients, don't hand its lifetime to a with block.

Retries are on by default: a failed idempotent request — a retryable status or no response at all — is sent again up to three times before the call gives up. Pass retry_options=0 to turn it off, for instance in a test that stubs an error response; the policy and its defaults are under Retries in the SDK map.

License

This SDK is distributed under the MIT License.

---

Support

Refer to the API reference for detailed information on available operations with code samples.

For further assistance, please contact support at pod-0@sellers.walmart.com.

---