Guides
My Account
  1. Items
  2. Create items on Walmart.com

Item search for the Walmart catalog

Overview

Use the Item Search API to determine whether Walmart already has the item you want to sell. Search the Walmart catalog by keyword (query) or by product identifier (upc, gtin, ean, or isbn).

In the US market, you can also search by asin when 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, then refine as needed.

Benefits

  • Faster item setup decisions: Quickly determine whether to use offer-only setup (MP_ITEM_MATCH) or full item setup (MP_ITEM).
  • Prefilled catalog attributes: Reuse Walmart catalog attributes so you only populate missing fields instead of starting from scratch.
  • Flexible search options: Use keyword search for broader discovery or product identifiers for precise matching.

How results are returned

Default response (responseFormat=DEFAULT or omitted)

Use the default response for keyword or identifier searches.

  • query: returns up to 40 matches.
  • upc, gtin, ean, or isbn: returns 0 or 1 match.

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

Use the spec-format response when you need item data formatted for an item setup workflow.

  • Provide exactly one identifier: upc, gtin, ean, isbn, or asin.
  • query is not supported.
  • The response returns 0 or 1 match.
  • If the item is found and is already live in the Walmart catalog, the API returns MP_ITEM_MATCH (offer setup by match).
  • If the item is found but is not live, the API returns MP_ITEM (full item setup) with available Walmart catalog attributes.
  • If no match is found, the API returns 200 with an empty JSON object ({}), and items may be omitted.

The Item Search API returns only items that are currently in a published status. Items that are unpublished, such as out-of-stock items or items affected by publishing restrictions, do not appear in search results.

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.
  • ean (string): European Article Number associated with the item. Example: 9781629381404.
  • isbn (string): International Standard Book Number associated with the item. Example: 1629381403.
  • asin (string): Amazon Standard Identification Number. Supported only in the US market when responseFormat=SPEC.
  • responseFormat (string, optional): Controls the response format. Allowed values: SPEC, DEFAULT. If omitted, the API uses DEFAULT.

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

Validation rules

  • responseFormat accepts SPEC or DEFAULT. Values are case sensitive. If omitted, the API uses DEFAULT.
  • When responseFormat=SPEC, provide exactly one of upc, gtin, ean, isbn, or asin.
  • Do not provide query when responseFormat=SPEC.
  • asin is supported only when responseFormat=SPEC.

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 exactly one identifier: upc, gtin, ean, isbn, or asin.

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

Step 1: Choose the response format

  • Use DEFAULT for standard keyword or identifier searches.
  • Use SPEC when you need a spec-compliant response for an item setup workflow.

Step 2: Build and send the request

Call GET /v3/items/walmart/search with the applicable search parameter.

  • For a default search, use query, upc, gtin, ean, or isbn.
  • For a spec-format search, set responseFormat=SPEC and provide exactly one of upc, gtin, ean, isbn, or asin. Do not include query in a spec-format request.

Step 3: 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 and debugging.
  • WM_SVC.NAME (required): Service name. Example: Walmart Marketplace.
  • WM_CONSUMER.CHANNEL.TYPE (optional): Channel identifier received during onboarding.
  • Accept: application/json.

Step 4: Review the response

For responseFormat=DEFAULT, the response contains an items array. Depending on the search, entries may include itemId, title, brand, price, images, condition, and signals such as isMarketPlaceItem.

For 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. The structure varies by feedType.

If the identifier resolves to an existing Walmart catalog item, the API returns MP_ITEM_MATCH. If the response requires full item setup, the API returns MP_ITEM.

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 for query parameter details, throttling expectations, and current status and error behavior.

Updated 28 days ago

Did this page help you?