Blog / API guides

Walmart Product Search API: Prices and Product Data

21 Aug 2026Updated 26 Oct 2026Perceptlayer7 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.

Why is there a gap between Walmart's own APIs and a product search API?

Walmart's affiliate programme 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 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: two endpoints, a free key, and JSON back. It is part of the Marketplaces APIs. 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.

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 cover both, and the quick start takes you from sign-up to a first call. You can also run the call in the playground on the Walmart search endpoint page 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.

A price-bounded, cheapest-first search looks like this:

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

{
  "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.

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 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/<id>), 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:

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 and retrying 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.

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 explain billing, and 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. 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:

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 cover setup. For the same pattern on a different source, see eBay search results as JSON.

Next step: get a free API key, run query=coffee+maker in the playground on the Walmart API page, then copy the cURL call into your own code.

walmartproduct searchecommercepricing datamarketplaces