--- updatedAt: 2026-08-12T20:16:28.000Z --- # Item search for the Walmart catalog ## Overview Use the **[Item Search API](/us-marketplace/reference/getsearchresult)** 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 ```http 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](/us-marketplace/docs/rate-limiting) 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 curl --request GET \ --url 'https://marketplace.walmartapis.com/v3/items/walmart/search?upc=716999676441' \ --header 'WM_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' ``` ```python import requests base_url = "https://marketplace.walmartapis.com/v3/items/walmart/search" headers = { "WM_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 curl --request GET \ --url 'https://marketplace.walmartapis.com/v3/items/walmart/search?asin=B08N5WRWNW&responseFormat=SPEC' \ --header 'WM_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' ``` ```python import requests url = "https://marketplace.walmartapis.com/v3/items/walmart/search" params = {"asin": "B08N5WRWNW", "responseFormat": "SPEC"} headers = { "WM_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`) ```json { "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](/us-marketplace/reference/getsearchresult) for query parameter details, throttling expectations, and current status and error behavior.