Python SDK

IntroCopy Anchor Link

The Walmart Seller API — Authorization SDK provides access to the Walmart Seller API — Authorization REST APIs.

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 dispatchCopy Anchor Link

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.

PostureCopy Anchor Link

• 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)Copy Anchor Link

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

InstallationCopy Anchor Link

Add the SDK to your project from its folder, with whichever package manager your project uses. Give each tool a path containing a slash, such as ../walmart-seller-api-authorization — a bare folder name is looked up on PyPI instead, and resolves to whatever project holds that name there:

pip install <path-to-sdk>

uv add <path-to-sdk>

poetry add <path-to-sdk>

Quick StartCopy Anchor Link

Synchronous clientCopy Anchor Link

Construct WalmartSellerApiAuthorizationClient with keyword arguments, and call close() when you are done. Every argument is optional.

from walmart_seller_api_authorization import WalmartSellerApiAuthorizationClient
from walmart_seller_api_authorization.auth import SellerAuthAuthorizationCodeScope, SellerAuthClientCredentialsScope
from walmart_seller_api_authorization.core import AuthorizationCodeCredentials, BasicAuthCredentials, ClientCredentials


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


client = WalmartSellerApiAuthorizationClient(
    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"),
    environment="production",
)

client.close()

Alternatively, scope it — with WalmartSellerApiAuthorizationClient(...) as client: closes the pool on exit.

Asynchronous clientCopy Anchor Link

AsyncWalmartSellerApiAuthorizationClient mirrors WalmartSellerApiAuthorizationClient 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_seller_api_authorization import AsyncWalmartSellerApiAuthorizationClient
from walmart_seller_api_authorization.auth import SellerAuthAuthorizationCodeScope, SellerAuthClientCredentialsScope
from walmart_seller_api_authorization.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 = AsyncWalmartSellerApiAuthorizationClient(
        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"),
        environment="production",
    )
    await client.aclose()


run(main())

Alternatively, scope it — async with AsyncWalmartSellerApiAuthorizationClient(...) as client: closes the pool on exit.