Use the Item Search API to determine whether Walmart already has the item you’re selling. You can search the Walmart catalog using keywords (for example, “MacBook” or “Apple”) or a product identifier such as UPC or GTIN.

You must specify at least one search parameter: query, upc, or gtin. You can also pass multiple query parameters together (and apply filters, when available) to narrow results and return more relevant matches. If multiple items match, the API returns the first 20 items.

Search results return items that are currently listed in Walmart. Review the product details in the response to decide whether you want to add an offer for a specific catalog item. If you want to sell a similar item that already exists in the catalog, you can also use the item setup information included in the results.

The response may include relatedQueries, which you can use to run follow-up searches for similar items.

Use cases

Check if Walmart already has your item: Search the catalog before creating anything new so you can decide whether to list against an existing catalog item.
Find the right match fast: Use UPC/GTIN for exact matching when you have identifiers; use keyword search when you’re exploring or don’t have identifiers yet.
Validate sellability and content: Review returned item details to confirm it’s the right product and assess whether you want to add an offer.
Discover alternatives: Use relatedQueries (when present) to run follow-up searches for similar or better-matching items.

Benefits

Reduces duplicate work: Helps you confirm whether an item already exists in the Walmart catalog before proceeding.
Flexible search options: Supports both broad discovery (keywords) and precise matching (identifiers).
Better decision-making from results: Returns useful catalog information to help you confidently choose what to sell.
More relevant results with refinement: You can combine multiple parameters (and filters, when available) to narrow and improve matches.

Reference guide

This guide explains how to use the Item Search API to find products in the Walmart.com global catalog by keyword, UPC, or GTIN, and how to interpret the results to decide whether you want to sell an item.

For full technical details, including endpoints, parameters, and brief descriptions, refer to the Item Search API Reference.

Endpoint

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

Query parameters (specify at least one)

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

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

Request sample

curl --request GET \ --url 'https://marketplace.walmartapis.com/v3/items/walmart/search?upc=716999676441&gtin=02917687511041' \ --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", "gtin": "02917687511041",
} resp = requests.get(base_url, headers=headers, params=params, timeout=30)
print("Status:", resp.status_code)
print(resp.text)

Modify your code

You can tailor search results by changing which query parameters you send. You must include at least one of query, upc, or gtin.

Choose your search input
- Use upc (12 digits) or gtin (14 digits) for the most precise matches.
- Use query for discovery, then refine by identifiers when possible.
Call the search endpoint
- Send a GET request to /v3/items/walmart/search with at least one of query, upc, or gtin.
1. Search by keyword only
  - Keep query=... and remove upc and gtin.
2. Search by UPC only
  - Keep upc=<12-digit upc> and remove query and gtin.
3. Search by GTIN only
  - Keep gtin=<14-digit gtin> and remove query and upc.
4. Combine parameters to narrow results
  - Use two or three parameters together (as in the sample cURL) to reduce ambiguity.
Send required headers and any optional headers as needed.
Review the response
- Inspect the items array for itemId, title, brand, price, images, condition, and availability signals like isMarketPlaceItem.
- If relatedQueries is present, use it to run additional searches for similar items.
- The API returns the first 20 matches when multiple items are found.
- Plan for throttling as part of your retry/backoff strategy.

Response sample

{ "items": [ { "itemId": "393016031", "condition": "New", "isMarketPlaceItem": true, "images": [ { "url": "http://i5.walmartimages.com/asr/556cc5a5-e729-4e48-b801-0146bbc97cdb_1.97507cfd7df5ca0fb6570e6a36495016.jpeg?odnHeight=180&odnWidth=180&odnBg=ffffff" }, { "url": "http://i5.walmartimages.com/asr/556cc5a5-e729-4e48-b801-0146bbc97cdb_1.97507cfd7df5ca0fb6570e6a36495016.jpeg?odnHeight=180&odnWidth=180&odnBg=ffffff" } ], "customerRating": "3.799999952316284", "price": { "amount": "12.989999771118164", "currency": "USD" }, "description": "<li>Designed for Apple <mark>iPad</mark> <mark>mini</mark> 1/2/3</li><li>Hybrid Silicone/PC Protective Shell with Kickstand</li><li>Shock-Absorption <mark><mark>Case</mark>s</mark> Protection <mark>Case</mark> for boys girls</li>", "title": "<mark>iPad</mark> <mark>mini</mark> 3/ 2 /1 <mark>Case</mark>, ULAK Three Layer Hybrid Heavy Duty Shockproof Protective <mark>Case</mark> with Kickstand for Apple <mark>iPad</mark> <mark>Mini</mark>,<mark>iPad</mark> <mark>Mini</mark> 2,<mark>iPad</mark> <mark>Mini</mark> 3", "brand": "ULAK", "productType": "VARIANT", "properties": { "variant_items_num": "5", "num_reviews": "16", "categories": [ "Electronics", "iPad & Tablets", "Apple iPad Accessories", "iPad Cases, Sleeves & Bags" ], "variants": { "variantMeta": [ { "name": "actual_color" } ], "variantData": [ { "productImageUrl": "https://i5.walmartimages.com/asr/82b8c484-651b-4e50-979c-42164649b8c5_1.bcf0b3a35d5767ee402c06b26a25f191.jpeg?odnHeight=180&odnWidth=180&odnBg=ffffff", "itemId": "936491618", "isAvailable": "Y", "title": "iPad mini 3/ 2 /1 Case, ULAK Three Layer Hybrid Heavy Duty Shockproof Protective Case with Kickstand for Apple iPad Mini,iPad Mini 2,iPad Mini 3", "variantValues": [ { "name": "actual_color", "value": "Black/Black" } ] }, { "productImageUrl": "https://i5.walmartimages.com/asr/e3d7c2bd-55d2-41ab-97b8-59c441918307_1.5f96dab5b8eddf4eb4857103a8c54913.jpeg?odnHeight=180&odnWidth=180&odnBg=ffffff", "itemId": "865777580", "isAvailable": "N", "title": "iPad mini 3 Case, iPad mini 2 Case, iPad mini Case, ULAK Three Layer Hybrid Heavy Duty Shockproof Protective Case with Kickstand for Apple iPad Mini,iPad Mini 2,iPad Mini 3", "variantValues": [ { "name": "actual_color", "value": "Black/Blue" } ] }, { "productImageUrl": "https://i5.walmartimages.com/asr/556cc5a5-e729-4e48-b801-0146bbc97cdb_1.97507cfd7df5ca0fb6570e6a36495016.jpeg?odnHeight=180&odnWidth=180&odnBg=ffffff", "itemId": "393016031", "isAvailable": "N", "title": "iPad mini 3/ 2 /1 Case, ULAK Three Layer Hybrid Heavy Duty Shockproof Protective Case with Kickstand for Apple iPad Mini,iPad Mini 2,iPad Mini 3", "variantValues": [ { "name": "actual_color", "value": "Blue+Lime Green" } ] }, { "productImageUrl": "https://i5.walmartimages.com/asr/5920a66b-a944-47c5-8ada-d1621d379ca9_1.4a20b40c528c6f8553f66043f38841e7.jpeg?odnHeight=180&odnWidth=180&odnBg=ffffff", "itemId": "451755050", "isAvailable": "Y", "title": "iPad mini 3/ 2 /1 Case, ULAK Three Layer Hybrid Heavy Duty Shockproof Protective Case with Kickstand for Apple iPad Mini,iPad Mini 2,iPad Mini 3", "variantValues": [ { "name": "actual_color", "value": "Mint Green/Grey" } ] }, { "productImageUrl": "https://i5.walmartimages.com/asr/ba395bef-48bf-46ac-8322-962e381c4e81_1.ea83239b1d41dc6e49521c2d1026f9f5.jpeg?odnHeight=180&odnWidth=180&odnBg=ffffff", "itemId": "800154739", "isAvailable": "Y", "title": "iPad Mini Case,iPad Mini 2 Case,iPad Mini 3 Case,iPad mini Retina Case,ULAK Three Layer Heavy Duty Shockproof Protective Case Cover Kickstand, Pink", "variantValues": [ { "name": "actual_color", "value": "Rose Gold/Rose Gold" } ] } ] }, "next_day_eligible": false } } ]
}

Results

After a successful call (200):

You receive an items array containing up to the first 20 matching items.
Each item includes a set of item attributes (for example, identifiers, condition, pricing, images, descriptive details, and other catalog metadata).

Next steps

Persist key identifiers such as itemId 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 (must include at least one of query, upc, or gtin), throttling expectations, and the latest status/error behavior before promoting changes to production.