Guides
My Account

Item search for the Walmart catalog

Overview

Use the Item Search API to quickly determine whether Walmart already has the item you want to sell. Search the Walmart catalog by keyword (query) or by product identifier (UPC, GTIN). In the US market, you can also search by ASIN (in addition to UPC or GTIN) and request spec-formatted results (responseFormat=SPEC).

When to use the Search API

  • Before item setup: Use the Item Search API as the first step in item setup to determine the correct setup path. Use offer-only (MP_ITEM_MATCH) when a match exists, or full item setup (MP_ITEM) when no match is found.
  • Accelerate full item setup: Pull available catalog attributes in spec format, so you only populate missing data.
  • For broader search and match exploration: Start with the default response (keyword search), then refine as needed.

Benefits

  • Faster item setup decisions: Quickly determines whether to use offer-only setup (MP_ITEM_MATCH) or full item setup (MP_ITEM).
  • Prefilled catalog attributes: Reuses Walmart catalog attributes so you only populate missing fields instead of starting from scratch.
  • Flexible search options: Supports broad discovery (keyword search) and precise matching (identifier lookup and spec-format).

How results are returned

Default response (responseFormat=DEFAULT or omitted)

  • Keyword search (query): returns up to 40 matches.
  • Identifier lookup (UPC or GTIN): returns 0 or 1 match.

Spec-format response (responseFormat=SPEC, US only)

  • Requires exactly one identifier (UPC, GTIN, or ASIN).

  • query is not supported.

  • Returns 0 or 1 match:

    • If the item is found and is already live in the Walmart catalog, returns MP_ITEM_MATCH (offer setup by match).
    • If the item is found but is not live, returns MP_ITEM (full item setup) with any available Walmart catalog attributes.

  • If no match is found, the API returns 200 with an empty JSON object ({}) and items may be omitted.

Endpoint

GET https://marketplace.walmartapis.com/v3/items/walmart/search

Query parameters

  • query (string): Keyword search based on descriptive terms (example: keyboard and mouse).
  • UPC (string): 12-digit Universal Product Code (example: 716999676441).
  • GTIN (string): 14-digit Global Trade Item Number (example: 02917687511041).
  • ASIN (string): Amazon Standard Identification Number (US only). Supported only when responseFormat=SPEC.
  • responseFormat(string, optional): Controls response format. Allowed values (case sensitive): SPEC, DEFAULT.
    • DEFAULT or omitted: returns the current response format.
    • SPEC (US only): returns a spec-compliant response intended for item setup workflows.

Throttling: Refer to the API throttling guide to understand the usage limitations for this API.

Validation rules

  • responseFormat must be SPEC or DEFAULT (uppercase only). If omitted, defaults to DEFAULT.
  • If responseFormat=SPEC (US only): send exactly one of UPC / GTIN / ASIN and do not send query.
  • If responseFormat=DEFAULT or omitted: send at least one of query / UPC / GTIN.

Request sample: default response

curl --request GET \ --url 'https://marketplace.walmartapis.com/v3/items/walmart/search?upc=716999676441' \ --header 'WM_CONSUMER.CHANNEL.TYPE: <consumer-channel-type>' \ --header 'WM_GLOBAL_VERSION: 3.1' \ --header 'WM_MARKET: mx' \ --header 'WM_QOS.CORRELATION_ID: b3261d2d-028a-4ef7-8602-633c23200af6' \ --header 'WM_SEC.ACCESS_TOKEN: eyJraWQiOiIzZjVhYTFmNS1hYWE5LTQzM.....' \ --header 'WM_SVC.NAME: Walmart Service Name' \ --header 'accept: application/json'
import requests base_url = "https://marketplace.walmartapis.com/v3/items/walmart/search" headers = { "WM_CONSUMER.CHANNEL.TYPE": "<consumer-channel-type>", "WM_GLOBAL_VERSION": "3.1", "WM_MARKET": "mx", "WM_QOS.CORRELATION_ID": "b3261d2d-028a-4ef7-8602-633c23200af6", "WM_SEC.ACCESS_TOKEN": "eyJraWQiOiIzZjVhYTFmNS1hYWE5LTQzM.....", "WM_SVC.NAME": "Walmart Service Name", "accept": "application/json",
} params = {"upc": "716999676441"} resp = requests.get(base_url, headers=headers, params=params, timeout=30)
print("Status:", resp.status_code)
print(resp.text)

Request sample: spec-format

For the spec-format flow, send one identifier only.

curl --request GET \ --url 'https://marketplace.walmartapis.com/v3/items/walmart/search?asin=B08N5WRWNW&responseFormat=SPEC' \ --header 'WM_CONSUMER.CHANNEL.TYPE: <consumer-channel-type>' \ --header 'WM_GLOBAL_VERSION: 3.1' \ --header 'WM_MARKET: US' \ --header 'WM_QOS.CORRELATION_ID: b3261d2d-028a-4ef7-8602-633c23200af6' \ --header 'WM_SEC.ACCESS_TOKEN: eyJraWQiOiIzZjVhYTFmNS1hYWE5LTQzM.....' \ --header 'WM_SVC.NAME: Walmart Service Name' \ --header 'accept: application/json'
import requests url = "https://marketplace.walmartapis.com/v3/items/walmart/search"
params = {"asin": "B08N5WRWNW", "responseFormat": "SPEC"} headers = { "WM_CONSUMER.CHANNEL.TYPE": "<consumer-channel-type>", "WM_GLOBAL_VERSION": "3.1", "WM_MARKET": "US", "WM_QOS.CORRELATION_ID": "b3261d2d-028a-4ef7-8602-633c23200af6", "WM_SEC.ACCESS_TOKEN": "eyJraWQiOiIzZjVhYTFmNS1hYWE5LTQzM.....", "WM_SVC.NAME": "Walmart Service Name", "Accept": "application/json",
} resp = requests.get(url, headers=headers, params=params, timeout=30)
resp.raise_for_status()
print(resp.json())

Modify your code

You can tailor search results by choosing a single search input per request: a keyword (query) or one identifier (UPC or GTIN). If you request spec-formatted results (responseFormat=SPEC), you must follow the additional request rules outlined below.

Step 1: Build and send the request

Choose one search input per request and call GET /v3/items/walmart/search.

  • Keyword search (default response): ...?query=<keywords>

  • Identifier lookup (default response): ...?upc=<upc> or ...?gtin=<gtin>

  • Spec-format (US only): add responseFormat=SPEC and exactly one identifier:

    • ...?upc=<upc>&responseFormat=SPEC or
    • ...?gtin=<gtin>&responseFormat=SPEC or
    • ...?asin=<asin>&responseFormat=SPEC

Rules for responseFormat=SPEC:**

  • Send exactly one of UPC / GTIN / ASIN
  • Do not include query

Step 2: Send required headers and any optional headers

  • WM_SEC.ACCESS_TOKEN (required): Access token obtained from the Token API
  • WM_QOS.CORRELATION_ID (required): Unique GUID per request for tracking/debugging
  • WM_SVC.NAME (required): Service name (example: Walmart Marketplace)
  • WM_CONSUMER.CHANNEL.TYPE (optional): Channel identifier received during onboarding
  • Accept: application/json

Step 3: Review the response

Default response structure: When responseFormat=DEFAULT (or omitted), the response returns:

  • An items array, which may include itemId, title, brand, price, images, condition, and signals like isMarketPlaceItem.
  • Default keyword searches return up to the first 40 matches.
  • Default identifier lookups (upc or gtin) and spec-format searches return 0 or 1 match.

Spec-format response structure: When responseFormat=SPEC, items contains up to one entry with:

  • feedType: MP_ITEM or MP_ITEM_MATCH
  • version: spec version
  • productType: present only for MP_ITEM
  • itemSpecPayload: spec payload containing MPItemFeedHeader metadata and an MPItem array (structure varies by feedType)

Spec selection behavior (deterministic): If the identifier is found in the Walmart catalog, the API returns MP_ITEM_MATCH (OSBM). If the identifier is not found, the API returns MP_ITEM (full setup). Only one response type is returned per request.

Response sample (spec-format MP_ITEM)

{ "items": [ { "feedType": "MP_ITEM", "version": "5.0.20260205-21_38_48-api", "productType": "Woodwind Instrument Replacement Parts", "itemSpecPayload": { "MPItemFeedHeader": { "locale": "en", "version": "5.0.20260205-21_38_48-api", "businessUnit": "WALMART_US" }, "MPItem": [ { "Orderable": { "specProductType": "Woodwind Instrument Replacement Parts", "batteryTechnologyType": "Does Not Contain a Battery", "productIdentifiers": { "productId": "06702124049005", "productIdType": "GTIN" }, "electronicsIndicator": "No", "releaseDate": "2000-01-01", "externalProductIdentifier": [ { "externalProductIdType": "ASIN", "externalProductId": "0001081753" } ], "chemicalAerosolPesticide": "No" }, "Visible": { "Woodwind Instrument Replacement Parts": { "warrantyText": "No", "isProp65WarningRequired": "No", "material": [ "Metal" ], "has_written_warranty": "No", "isCollectible": "No", "netContent": { "productNetContentUnit": "Each", "productNetContentMeasure": 1 }, "shortDescription": "This comprehensive sheet music for wind ensemble, titled \"Quasi improvvisando,\" features parts for a wide array of woodwind and brass instruments. It includes arrangements for Flute, Piccolo, 2 Oboes, Clarinet, Bass Clarinet, Bassoon, Contrabassoon, 2 French Horns, and Trumpet (C).", "keyFeatures": [ "Quasi Improvvisando Wind Ensemble Sheet Music for Flute, Piccolo, Oboes, Clarinet, Bassoon, French Horns, Trumpet:", "Musical Instrument Style: Wind Ensemble", "Instruments Included: Flute, Piccolo, 2 Oboes, Clarinet, Bass Clarinet, Bassoon, Contrabassoon, 2 French Horns, Trumpet (C)", "Format: Sheet Music Partition", "Manufacturer ID: ED6762", "Publication Date: January 1, 2000" ], "brand": "Jean Franaix", "warrantyURL": "https://www.toolweb.com/", "productName": "Quasi Improvvisando Wind Ensemble Sheet Music for Flute, Piccolo, Oboes, Clarinet, Bassoon, French Horns, Trumpet", "prop65WarningText": "California residents: This product can expose you to chemicals including diethylhexyl phthalate or lead, which are known to the State of California to cause cancer and birth defects or other reproductive harm. For more information go to www.P65Warnings.ca.gov." } } } ] } } ]
}

Next steps

  • Persist key identifiers for downstream catalog and listing workflows.
  • Add request logging with WM_QOS.CORRELATION_ID for traceability and support.
  • Refer to the API reference documentation to confirm query parameter rules, throttling expectations, and the latest status/error behavior before promoting changes to production.

Updated 6 days ago