Metadata-Version: 2.4
Name: apimatic-wm-v4-sdk
Version: 0.0.3
Summary: This is a sample SDK generated by APIMatic
License-Expression: MIT
License-File: LICENSE
Keywords: apimatic,sdksio
Author: developer sdksio
Author-email: developer+sdksio@apimatic.io
Maintainer: APIMatic
Maintainer-email: support@apimatic.io
Requires-Python: >=3.10
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Typing :: Typed
Classifier: Operating System :: OS Independent
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Dist: certifi (>=2024.7.4)
Requires-Dist: httpx2 (>=2.13.1,<3.0.0)
Requires-Dist: pydantic[email] (>=2.11.0,<3.0.0)
Requires-Dist: typing-extensions (>=4.13.0,<5.0.0)
Project-URL: Documentation, https://apimatic.io
Description-Content-Type: text/markdown

# Walmart APIs SDK

[![Built with APIMatic][apimatic-badge]][apimatic-url] [![License: MIT][license-badge]][license-url] [![Python 3.10+][python-badge]][python-url]

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

> [!TIP]
> **Looking for a specific signature, model, enum, or error type?** This SDK ships a generated
> **[SDK map](sdk-map.md)** -- a lookup index of the SDK's entire Python surface. Consult it before
> scanning the source tree; details under [SDK map](#sdk-map).

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

<!-- hello: Atul Soman (@a0s1r2d) joined Pod 4 — 2026-06-04 -->
<!-- hello: Ramprabhu Murugesan (@rmurug3) joined Pod 4 as lead — 2026-06-04 -->, 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)
<!-- hello: Vikram Godbole (@vgodbol) joined Pod 2 — 2026-06-03 -->
<!-- hello: Suresh Dussa (@s0d08o6) joined Pod 2 — 2026-06-08 -->
<!-- hello: Leon Jiang (@r0j09pq) joined Pod 2 — 2026-08-10 -->
<!-- hello: Rashmi Das (@r0d01sm) joined Pod 2 — 2026-08-18 -->, 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:

```bash
pip install apimatic-wm-v4-sdk
```

```bash
uv add apimatic-wm-v4-sdk
```

```bash
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:

```bash
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](sdk-map.md).

```python
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](#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](sdk-map.md). 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`.

```python
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](#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](api-reference.md)** | 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](raw-api-reference.md)** | 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`](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`](sdk-map.md).

## Best Practices

> [!TIP]
> Use a **single `WalmartApisClient` instance** for the lifetime of your application and reuse it across
> all requests. Each instance owns its own connection pool, so an instance per request forfeits
> connection reuse and leaks pools that are never closed.

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][license-url].

---

## Support

Refer to the [API reference](api-reference.md) for detailed information on available operations with code samples.

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

---

[license-url]: LICENSE
[license-badge]: https://img.shields.io/badge/License-MIT-blue.svg
[apimatic-url]: https://www.apimatic.io
[apimatic-badge]: https://www.apimatic.io/hubfs/Built-with-APIMatic-badge.svg
[python-url]: https://www.python.org/downloads/
[python-badge]: https://img.shields.io/badge/python-3.10%2B-blue.svg

