Getting Started with Walmart APIs

Introduction

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

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>.
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

, 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

Install the gem from the command line:

gem install walmart-apimatic-sdk -v 0.0.2

Or add the gem to your Gemfile and run bundle:

gem 'walmart-apimatic-sdk', '0.0.2'

For additional gem details, see the RubyGems page for the walmart-apimatic-sdk gem.

IRB Console Usage

You can explore the SDK interactively using IRB in two ways

1. Use IRB with Installed Gem

Open your system terminal (Command Prompt, Git Bash or macOS Terminal) and type the following command to start the irb console.

irb

Now you can load the SDK in the IRB

require 'walmart_ap_is'
include WalmartApIs

2. Use IRB within SDK

Open your system terminal (Command Prompt, Git Bash or macOS Terminal) and navigate to the root folder of SDK.

cd path/to/walmart_ap_is

Now you can start the preconfigured irb console by running the following command

ruby bin/console

Note: This automatically loads the SDK from lib/

Initialize the API Client

Note: Documentation for the client can be found here.

The following parameters are configurable for the API Client:

Parameter	Type	Description
environment	`Environment`	The API environment. Default: `Environment.PRODUCTION`
connection	`Faraday::Connection`	The Faraday connection object passed by the SDK user for making requests
adapter	`Faraday::Adapter`	The Faraday adapter object passed by the SDK user for performing http requests
timeout	`Float`	The value to use for connection timeout. Default: 30
max_retries	`Integer`	The number of times to retry an endpoint call if it fails. Default: 0
retry_interval	`Float`	Pause in seconds between retries. Default: 1
backoff_factor	`Float`	The amount to multiply each successive retry's interval amount by in order to provide backoff. Default: 2
retry_statuses	`Array`	A list of HTTP statuses to retry. Default: [408, 413, 429, 500, 502, 503, 504, 521, 522, 524]
retry_methods	`Array`	A list of HTTP methods to retry. Default: %i[get put]
http_callback	`HttpCallBack`	The Http CallBack allows defining callables for pre and post API calls.
proxy_settings	`ProxySettings`	Optional proxy configuration to route HTTP requests through a proxy server.
logging_configuration	`LoggingConfiguration`	The SDK logging configuration for API calls
seller_auth_authorization_code_credentials	`SellerAuthAuthorizationCodeCredentials`	The credential object for OAuth 2 Authorization Code Grant
seller_auth_client_credentials_credentials	`SellerAuthClientCredentialsCredentials`	The credential object for OAuth 2 Client Credentials Grant
basic_client_auth_credentials	`BasicClientAuthCredentials`	The credential object for Basic Authentication
wallet_auth_credentials	`WalletAuthCredentials`	The credential object for OAuth 2 Client Credentials Grant

The API client can be initialized as follows:

Code-Based Client Initialization

require 'walmart_ap_is'
include WalmartApIs

client = Client.new(
  seller_auth_authorization_code_credentials: SellerAuthAuthorizationCodeCredentials.new(
    oauth_client_id: 'OAuthClientId',
    oauth_client_secret: 'OAuthClientSecret',
    oauth_redirect_uri: 'OAuthRedirectUri',
    oauth_scopes: [
      OauthScopeSellerAuthAuthorizationCode::SELLER_APICATALOGREAD,
      OauthScopeSellerAuthAuthorizationCode::SELLER_APICATALOGWRITE
    ]
  ),
  seller_auth_client_credentials_credentials: SellerAuthClientCredentialsCredentials.new(
    oauth_client_id: 'OAuthClientId',
    oauth_client_secret: 'OAuthClientSecret',
    oauth_scopes: [
      OauthScopeSellerAuthClientCredentials::SELLER_APICATALOGREAD,
      OauthScopeSellerAuthClientCredentials::SELLER_APICATALOGWRITE
    ]
  ),
  basic_client_auth_credentials: BasicClientAuthCredentials.new(
    username: 'Username',
    password: 'Password'
  ),
  wallet_auth_credentials: WalletAuthCredentials.new(
    oauth_client_id: 'OAuthClientId',
    oauth_client_secret: 'OAuthClientSecret',
    oauth_scopes: [
      OauthScopeWalletAuth::CATALOGREAD,
      OauthScopeWalletAuth::ANALYTICSREAD
    ]
  ),
  environment: Environment::PRODUCTION,
  logging_configuration: LoggingConfiguration.new(
    log_level: Logger::INFO,
    request_logging_config: RequestLoggingConfiguration.new(
      log_body: true
    ),
    response_logging_config: ResponseLoggingConfiguration.new(
      log_headers: true
    )
  )
)

Environment-Based Client Initialization

require 'walmart_ap_is'
include WalmartApIs

# Create client from environment
client = Client.from_env

See the Environment-Based Client Initialization section for details.

Environments

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

Fields

Name	Description
PRODUCTION	Default Production
ENVIRONMENT2	Sandbox