--- title: "Walmart Product Search API: Prices and Product Data" description: "Search Walmart by keyword and get price, rating, seller and stock as JSON with GET /v1/walmart/search. Parameters, a real response and a credit count." url: https://perceptlayer.com/blog/walmart-product-search-api --- [Blog](https://perceptlayer.com/blog) / [API guides](https://perceptlayer.com/blog/category/api-guides) # Walmart Product Search API: Prices and Product Data 21 Aug 2026 Updated 26 Oct 2026 Perceptlayer 7 min read Call `GET /v1/walmart/search` with a `query` and you get Walmart search results as JSON: item ID, title, price, rating, review count, seller and stock status. Call `GET /v1/walmart/product` with a `us_item_id` to look up one item. Each successful call costs 1 credit, and failed calls cost nothing. This guide covers both endpoints, every parameter, a recorded response and the credit cost of a 10,000-product pass. ## Key takeaways - `GET /v1/walmart/search` needs only `query`; `page`, `sort`, `min_price`, `max_price`, `cat_id` and `facet_filter` are optional. - `GET /v1/walmart/product` takes one required parameter, `us_item_id`, which is the `us_item_id` field every search result carries. - Both endpoints cost 1 credit per successful call, so a detail lookup for 10,000 products costs 10,000 credits. - The search response already includes `price`, `rating`, `reviews`, `seller_name` and `availability_status`, so many price-monitoring jobs never need the detail call. - Failed calls return `X-Credits-Used: 0`, and the free tier gives 1,000 credits a month with no credit card. ## Why is there a gap between Walmart's own APIs and a product search API? Walmart's [affiliate programme](https://affiliates.walmart.com/) is built for publishers: it lets them "earn commission by connecting your audience to products they love", with link generation and data feeds in its Affiliate Member Center (Walmart, 2026). Walmart's [developer portal](https://developer.walmart.com/) is aimed at marketplace sellers, solutions providers, first-party suppliers, carriers and advertising partners, to manage items, prices, orders and ads (Walmart, 2026). Both are built for partners, not for someone who just wants search results with prices and stock as JSON. If you are a publisher earning commission, start with the affiliate programme. If you sell on Walmart, the developer portal is the place. If you are a data team or agent builder who needs search results across a catalogue, that is the job of the [Walmart API](https://perceptlayer.com/apis/walmart): two endpoints, a free key, and JSON back. It is part of the [Marketplaces APIs](https://perceptlayer.com/verticals/marketplaces). Data is collected from publicly available sources and returned as found at the time of the call. ## How do you search Walmart products with one request? Send a GET request to `/v1/walmart/search` with the `query` parameter and your key in the `X-API-Key` header. The response is JSON with a `results` array, a `search_metadata` object and a `pagination` object. `query` can be up to 500 characters. Everything else is optional. ```bash curl "https://api.perceptlayer.com/v1/walmart/search?query=coffee+maker" \ -H "X-API-Key: $API_KEY" ``` Keys start with `sk_live_`. If a header isn't possible, the `api_key` query parameter works too. The [authentication docs](https://docs.perceptlayer.com/authentication) cover both, and the [quick start](https://docs.perceptlayer.com/quickstart) takes you from sign-up to a first call. You can also run the call in the playground on the [Walmart search endpoint page](https://perceptlayer.com/apis/walmart/search) before writing code. ## Which parameters does the search endpoint take? The search endpoint takes one required parameter, `query`, and six optional ones for paging, sorting, price bounds, category and facet filters. Types and limits below are the only ones documented, so this guide doesn't state defaults or page sizes. If you need a page size, read it from a real response rather than assuming. | Parameter | Type | Required | Notes | | --- | --- | --- | --- | | `query` | string | yes | Up to 500 characters | | `page` | integer | no | Page of results to return | | `sort` | string | no | One of `best_match`, `price_low`, `price_high`, `rating_high`, `new` | | `min_price` | integer | no | Lower price bound | | `max_price` | integer | no | Upper price bound | | `cat_id` | string | no | Category ID, up to 64 characters | | `facet_filter` | string | no | Up to 2,000 characters | A price-bounded, cheapest-first search looks like this: ```bash curl "https://api.perceptlayer.com/v1/walmart/search?query=air+fryer&sort=price_low&min_price=20&max_price=80" \ -H "X-API-Key: $API_KEY" ``` Bad values come back as `invalid_parameters` (422), with a `request_id` you can quote. The [errors docs](https://docs.perceptlayer.com/errors) list every code. ## What does a search response look like? A successful search returns `success: true`, a `data` object and a `meta` object. Inside `data`, `search_metadata` echoes your query, page and sort and reports `total_items`; `results` holds one object per product; `pagination` tells you whether to keep going. This excerpt is from a recorded call for `query=air+fryer`, trimmed to the first result with its `thumbnail` URL shortened ( `…` marks each cut): ```json { "success": true, "data": { "search_metadata": { "query": "air fryer", "page": 1, "sort": "best_match", "total_items": 72 }, "results": [ { "us_item_id": "17268119743", "title": "Instant Pot 4QT VORTEX 6-in-1 Mini Air Fryer, Air fry, Bake, Roast, Broil, Dehydrate or Reheat, Black, 4 Quarts", "price": 89.99, "currency": "USD", "rating": 4.4, "reviews": 87, "seller_name": "Walmart.com", "availability_status": "IN_STOCK", "thumbnail": "https://i5.walmartimages.com/seo/Instant-Pot-4QT-VORTEX-6-in-1-Mini-Air-Fryer-…", "product_page_url": "https://www.walmart.com/ip/17268119743", "out_of_stock": false, "sponsored": true }, … ], "pagination": { "current_page": 1, "max_page": 13, "has_more": true } }, "meta": { "endpoint_family": "search", "duration_ms": 4134, "attempts": 2 } } ``` Two fields are worth checking before you rely on the data. Both recorded results show `sponsored: true`, so look at that flag before treating the order as organic ranking. `seller_name` is `Walmart.com` in both. Check it across your own queries to see what other values appear. The `thumbnail` field is an image URL. ## How do you look up a single Walmart product? Pass the `us_item_id` from a search result to `GET /v1/walmart/product`. It's the only parameter, it's required, and it can be up to 32 characters. The call returns the Product record for that item and costs 1 credit, the same as a search page. ```bash curl "https://api.perceptlayer.com/v1/walmart/product?us_item_id=17268119743" \ -H "X-API-Key: $API_KEY" ``` We haven't recorded a product response for this guide, so we won't show one here. The [Walmart product endpoint page](https://perceptlayer.com/apis/walmart/product) lists what it returns, and the playground there runs a real call with your key. In the recorded results, the `us_item_id` is also the last part of each `product_page_url` ( `https://www.walmart.com/ip/`), which helps if you already hold product links and want to skip search. ## What is the search-then-detail pattern? Run a search to discover item IDs and headline fields, then call the product endpoint only for items you need more about. A search page costs 1 credit and a detail lookup costs 1 credit for a single item, so search is cheaper per product only if a page holds more than one item. The page size isn't documented, and the recorded excerpt shows only two results, so measure items per page on your own queries before you decide how much to lean on search. Here is a Python loop that walks every page of a search using the `has_more` flag from the response, collecting item IDs: ```python import os import requests BASE = "https://api.perceptlayer.com" HEADERS = {"X-API-Key": os.environ["API_KEY"]} def search_all(query, **filters): page, items = 1, [] while True: r = requests.get( f"{BASE}/v1/walmart/search", headers=HEADERS, params={"query": query, "page": page, **filters}, timeout=60, ) r.raise_for_status() data = r.json()["data"] items.extend(data["results"]) if not data["pagination"]["has_more"]: return items page += 1 items = search_all("air fryer", sort="price_low") organic = [i for i in items if not i["sponsored"]] print(len(items), len(organic)) ``` For retries and page-loop safety, see [safe page loops in Python](https://perceptlayer.com/blog/paginate-web-data-api-python) and [retrying without paying twice](https://perceptlayer.com/blog/retry-web-api-calls-without-paying-twice). A timed-out request may have succeeded and been billed, because requests have no idempotency key. ## What does a 10,000-product catalogue pass cost? A detail lookup for 10,000 products costs 10,000 calls × 1 credit = 10,000 credits, which equals the Starter pack exactly. The discovery step is extra: every search page is 1 credit. The recorded `air fryer` search reported `max_page` 13, so walking that one query end to end costs 13 credits. | Step | Calls | Credits per call | Credits | | --- | --- | --- | --- | | Walk one query (the recorded example, 13 pages) | 13 | 1 | 13 | | Detail lookup for 10,000 items | 10,000 | 1 | 10,000 | | Search-only refresh of 10,000 items | ⌈10,000 ÷ items per page⌉ | 1 | the same number, measured on your own queries | The third row is a formula, not a figure. Items per page isn't documented, so count it in a real response and divide 10,000 by that number to get the credits for a search-only refresh. A single query also reports only so many items (72 in the recorded call), so reaching 10,000 products takes many queries, and the same product can appear in more than one. Search results already carry `price`, `availability_status`, `rating` and `reviews`, so a price monitor can refresh from search pages and call the product endpoint only when a field you need is missing. The [credits docs](https://docs.perceptlayer.com/credits) explain billing, and [pricing](https://perceptlayer.com/pricing) shows what credits cost. Purchased credits last 12 months, with no subscription. At 1 request a second on the free tier, 10,000 sequential detail calls take about 10,000 seconds, so plan for the [rate limits](https://docs.perceptlayer.com/rate-limits). Paid packs include higher rates. A 429 carries a `Retry-After` header, and you should wait that many seconds. ## Can an AI agent call the Walmart endpoints? Yes. The MCP server at `https://api.perceptlayer.com/mcp` exposes `search_endpoints`, `get_endpoint` and `call_endpoint`. An agent finds the Walmart endpoints in the catalogue for free, then calls them with the same parameters as above. Only a successful `call_endpoint` spends credits, and the result reports credits used and remaining. In Claude Code, add it with one command: ```bash claude mcp add --transport http perceptlayer https://api.perceptlayer.com/mcp --header "Authorization: Bearer $API_KEY" ``` A shopping agent can then search, filter out `sponsored` items and fetch one product for a final check. The [AI agents docs](https://docs.perceptlayer.com/ai-agents) cover setup. For the same pattern on a different source, see [eBay search results as JSON](https://perceptlayer.com/blog/ebay-item-search-data-json). Next step: [get a free API key](https://perceptlayer.com/signup), run `query=coffee+maker` in the playground on the [Walmart API page](https://perceptlayer.com/apis/walmart), then copy the cURL call into your own code. ## APIs in this post - [Walmart **1 credit per call** · 2 endpoints](https://perceptlayer.com/apis/walmart) ## Frequently asked questions ### How many credits does a Walmart search cost? A successful call to `GET /v1/walmart/search` costs 1 credit, and so does `GET /v1/walmart/product`. A failed call costs nothing and returns `X-Credits-Used: 0`. Every successful response also carries `X-Credits-Remaining`, so you can track your balance. The free tier gives 1,000 credits a month. ### Does the API return Walmart prices in dollars? Each search result carries a numeric `price` and a `currency` field; the recorded sample shows `USD`. Prices are returned as found at the time of the call, so they can change between a search and a later product lookup. Store the call time next to the price if you track history. ### How do I get the next page of Walmart results? Check `data.pagination.has_more`. When it is true, repeat the same request with `page` increased by one. The response also gives `current_page` and `max_page`, and the recorded example reported 13 pages. Each page is a separate call that costs 1 credit. ### What happens if I run out of credits mid-run? The service is prepaid, so calls return `insufficient_credits` (402) once the balance is gone, and nothing more is debited. There's no automatic top-up. Check `X-Credits-Remaining` during long loops and stop cleanly; the [errors docs](https://docs.perceptlayer.com/errors) list the codes to handle. ### Can I use this instead of Walmart's official API? It depends on your use. If you earn commission through Walmart links, start with Walmart's own [affiliate programme](https://affiliates.walmart.com/). If you sell on Walmart, see its [developer portal](https://developer.walmart.com/). If you need product data for analysis, monitoring or an agent, a keyed JSON endpoint is the more direct path. ### Should I build a Walmart scraper instead? A Walmart scraper means maintaining selectors for product and search pages, handling blocks, and following Walmart's terms. The search endpoint returns price, rating, seller and stock as named JSON fields for 1 credit per successful call, with nothing charged for failures. Build your own only for a page the endpoints don't cover, and check the response in the playground first. walmart product search ecommerce pricing data marketplaces ## More from the blog 1. [API guides](https://perceptlayer.com/blog/category/api-guides) 22 Oct 2026 Perceptlayer 9 min read ## [Idealo API: Compare Product Prices Across Shops as JSON](https://perceptlayer.com/blog/idealo-api-price-comparison-json) Search idealo.de by keyword, then pass a product\_id to the offers endpoint. Endpoints, parameters, a real search response and the cost at 1 credit per call. 2. [API guides](https://perceptlayer.com/blog/category/api-guides) 16 Oct 2026 Perceptlayer 7 min read ## [Kleinanzeigen API: Search German Classifieds as JSON](https://perceptlayer.com/blog/kleinanzeigen-api-search-json) Search Kleinanzeigen ads by query, city, category and price range with one GET call. Parameters, a real response and the cost: 1 credit per call. 3. [API guides](https://perceptlayer.com/blog/category/api-guides) 14 Oct 2026 Perceptlayer 6 min read ## [Vinted API: Search Second-Hand Items as JSON](https://perceptlayer.com/blog/vinted-api-search-items-json) Search Vinted as JSON with 14 optional parameters, then price-check one query across 19 countries. Each call costs 1 credit; failed calls cost nothing.