WMApimaticSDK 0.0.5

Getting Started with Walmart APIs

Introduction

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 authorization-service as a stateless proxy to Walmart IAM (ADR-026): 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 (ADR-023 for seller-direct, ADR-048 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 (ADR-023): 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 (ADR-048): 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 (ADR-048, 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 ADR-048. authorization-service 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: authorization-service (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. Pod lead: annotate ops with x-walmart-status: applicable | not-applicable | adapted., 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. Pod lead: annotate ops with x-walmart-status: applicable | not-applicable | adapted., WFS Inbound Packing. Walmart Seller API — Fulfillment Inbound contract. Terminology: WFS = Walmart Fulfillment Services, Ship Node = fulfillment center. Pod lead: annotate ops with x-walmart-status: applicable | not-applicable | adapted., WFS Inbound Packing & Placement API. Walmart Seller API — Fulfillment Inbound contract. Terminology: WFS = Walmart Fulfillment Services, Ship Node = fulfillment center. Pod lead: annotate ops with x-walmart-status: applicable | not-applicable | adapted., WFS Inbound Items, Compliance, Labels & Prep API. Walmart Seller API — Fulfillment Inbound contract. Terminology: WFS = Walmart Fulfillment Services, Ship Node = fulfillment center. Pod lead: annotate ops with x-walmart-status: applicable | not-applicable | adapted., WFS Inbound Shipments API. Walmart Seller API — Fulfillment Inbound contract. Terminology: WFS = Walmart Fulfillment Services, Ship Node = fulfillment center. Pod lead: annotate ops with x-walmart-status: applicable | not-applicable | adapted., 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, Mirrored from SP-API reference (as-is). Pod lead to annotate each operation with x-walmart-status: applicable | not-applicable | adapted. Source: https://github.com/amzn/selling-partner-api-models, 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. merchant-fulfillment-service is obsolete: its operations are covered by shipping-service, and both front the same upstream (Ship With Walmart). Per Suresh's SWW-consolidation analysis, every operation below is marked x-walmart-status: not-applicable + deprecated: true, so it no longer 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 shipping-service.

Tracking: RCTPAPI-21191 (this deprecation). The one partial-coverage gap (MFN full-record getShipment has no single shipping-service equivalent) is owned by Suresh for decision in RCTPAPI-21192.

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 (ADR-047).

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 (ADR-034, ADR-047).

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

Domain Owner: Payments Domain (consolidated Pod 5 + Pod 6) Tech Lead: @cssehga Replaces: aurora-payments-settlement-service (v3 BFF); finances-service (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 (ADR-029).

Three GET endpoints are backed by IQS / GCI catalog_index (RCTPAPI-20619). Five batch/item endpoints are Phase 1 stubs pending implementation — see RCTPAPI-20855 through RCTPAPI-20859.

Pod Owner: Pod 3 — Inventory & Pricing Implementation target: Walmart Price Service / Competitive Intelligence, Mirrored from SP-API reference (as-is). Pod lead to annotate each operation with x-walmart-status: applicable | not-applicable | adapted. Source: https://github.com/amzn/selling-partner-api-models, Fee estimate endpoints for seller items. Aligned to SP-API productFeesV0 surface, with Walmart Item ID substituted for ASIN as the primary item identifier (ADR-029), 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, Mirrored from SP-API reference (as-is). Pod lead to annotate each operation with x-walmart-status: applicable | not-applicable | adapted. Source: https://github.com/amzn/selling-partner-api-models, 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, Walmart Seller API contract. Pod lead to annotate each operation with x-walmart-status: applicable | not-applicable | adapted., Walmart Seller API contract. Pod lead to annotate each operation with x-walmart-status: applicable | not-applicable | adapted., Walmart Seller API contract. Pod lead to annotate each operation with x-walmart-status: applicable | not-applicable | adapted., Walmart Seller API contract. Pod lead to annotate each operation with x-walmart-status: applicable | not-applicable | adapted., 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 merchant-fulfillment-service; ADR-008 (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

Install the Package

If you are building with .NET CLI tools then you can also use the following command:

dotnet add package WMApimaticSDK --version 0.0.5

You can also view the package at: https://www.nuget.org/packages/WMApimaticSDK/0.0.5

Initialize the API Client

Note: Documentation for the client can be found here.

The following parameters are configurable for the API Client:

The API client can be initialized as follows:

Code-Based Initialization

using Microsoft.Extensions.Logging;
using System.Collections.Generic;
using WalmartApIs.Standard;
using WalmartApIs.Standard.Authentication;
using WalmartApIs.Standard.Models;

namespace ConsoleApp;

WalmartApIsClient client = new WalmartApIsClient.Builder()
    .SellerAuthAuthorizationCodeCredentials(
        new SellerAuthAuthorizationCodeModel.Builder(
            "OAuthClientId",
            "OAuthClientSecret",
            "OAuthRedirectUri"
        )
        .OauthScopes(
            new List<OauthScopeSellerAuthAuthorizationCode>
            {
                OauthScopeSellerAuthAuthorizationCode.SellerApicatalogread,
                OauthScopeSellerAuthAuthorizationCode.SellerApicatalogwrite,
            })
        .Build())
    .SellerAuthClientCredentialsCredentials(
        new SellerAuthClientCredentialsModel.Builder(
            "OAuthClientId",
            "OAuthClientSecret"
        )
        .OauthScopes(
            new List<OauthScopeSellerAuthClientCredentials>
            {
                OauthScopeSellerAuthClientCredentials.SellerApicatalogread,
                OauthScopeSellerAuthClientCredentials.SellerApicatalogwrite,
            })
        .Build())
    .BasicClientAuthCredentials(
        new BasicClientAuthModel.Builder(
            "Username",
            "Password"
        )
        .Build())
    .WalletAuthCredentials(
        new WalletAuthModel.Builder(
            "OAuthClientId",
            "OAuthClientSecret"
        )
        .OauthScopes(
            new List<OauthScopeWalletAuth>
            {
                OauthScopeWalletAuth.Catalogread,
                OauthScopeWalletAuth.Analyticsread,
            })
        .Build())
    .HttpClientConfig(httpClientConfig =>
        httpClientConfig.Timeout(TimeSpan.FromSeconds(100)))
    .Environment(WalmartApIs.Standard.Environment.Production)
    .LoggingConfig(config => config
        .LogLevel(LogLevel.Information)
        .RequestConfig(reqConfig => reqConfig.Body(true))
        .ResponseConfig(respConfig => respConfig.Headers(true))
    )
    .Build();

Configuration-Based Initialization

using WalmartApIs.Standard;
using Microsoft.Extensions.Configuration;

namespace ConsoleApp;

// Build the IConfiguration using .NET conventions (JSON, environment, etc.)
var configuration = new ConfigurationBuilder()
    .AddJsonFile("config.json")
    .AddEnvironmentVariables() // [optional] read environment variables
    .Build();

// Instantiate your SDK and configure it from IConfiguration
var client = WalmartApIsClient
    .FromConfiguration(configuration.GetSection("WalmartApIs"));

See the Configuration-Based Initialization section for details.

Environments

The SDK can be configured to use a different environment for making API calls. Available environments are:

Fields

Authorization

This API uses the following authentication schemes.

• sellerAuth_authorization_code (OAuth 2 Authorization Code Grant)
• sellerAuth_client_credentials (OAuth 2 Client Credentials Grant)
• basicClientAuth (Basic Authentication)
• walletAuth (OAuth 2 Client Credentials Grant)

List of APIs

• Authorization
• Catalog
• Data Kiosk
• Feeds
• Wfs Inbound
• Fulfillment Outbound
• Inventory
• Wfs Inventory
• Fba Inventory
• Listings Items
• Listings Restrictions
• Merchant Fulfillment
• Orders
• Settlement
• Reconciliation
• Reports
• Payouts
• Disputes
• Final Payout
• Finances
• Product Pricing
• Product Fees
• Fees
• Product Type Definitions
• Report Schedules
• Sales
• Solicitations
• Messaging
• Notifications
• Sellers
• Shipping
• Uploads

SDK Infrastructure

Configuration

• Configuration-Based Initialization
• HttpClientConfiguration
• HttpClientConfigurationBuilder
• LogBuilder
• LogRequestBuilder
• LogResponseBuilder
• ProxyConfigurationBuilder

HTTP

• HttpCallback
• HttpContext
• HttpRequest
• HttpResponse
• HttpStringResponse

Utilities

• ApiException
• ApiResponse
• ApiHelper
• CustomDateTimeConverter
• UnixDateTimeConverter