scavio-walmart

Walmart via Scavio

Search Walmart, read a product in full, page its customer reviews, list a category, look up the buy-box offer on an item, and read a marketplace seller's storefront and catalog. All endpoints return structured JSON.

When to trigger

Use this skill when the user asks to:

• Search Walmart for products by keyword, price band or sort order
• Look up a Walmart item by its item id (usItemId)
• Read customer reviews and the rating breakdown for a Walmart product
• List the products inside a Walmart category
• Check who holds the buy box on a Walmart listing and at what price
• Look up a Walmart marketplace seller: rating, review count, Pro Seller badge
• See what a Walmart marketplace seller lists
• Compare Walmart pricing against another retailer (pair with scavio-amazon, scavio-ebay or scavio-target)
• Search the Canadian (walmart.ca) or Mexican (walmart.com.mx) marketplace

Setup

Get a free API key at https://scavio.dev (50 free credits to get started, no card required):

export SCAVIO_API_KEY=sk_live_your_key

Every request is a POST with a JSON body and:

Authorization: Bearer $SCAVIO_API_KEY

Endpoints

Base URL: https://api.scavio.dev.

Cost rule

Cost is a function of the request body, not a constant. domain is the only price-bearing parameter:

• domain: "com" (US, the default) costs 1 credit
• domain: "ca" (Canada) costs 1 credit
• domain: "com.mx" (Mexico) costs 2 credits

Only /search and /category accept domain, so only those two can ever cost 2. The other five endpoints are always 1 credit. Never quote a flat price for search or category without stating the domain rule.

Workflow

1. Find items: call /walmart/search with query. The item id is id on each row of data.products[] — that is the value the other endpoints take as product_id.
2. Read an item: call /walmart/product with product_id.
3. Reviews: call /walmart/reviews with the same product_id, paging with page (10 reviews per page).
4. Browse a category: call /walmart/category with category_id.
5. Buy box: call /walmart/offers with product_id to see who currently wins the buy box and at what price.
6. Sellers: a product, search or offers response carries seller_catalog_id. Pass that numeric id as seller_id to /walmart/seller for the storefront and to /walmart/seller-products for the catalog.

search, reviews and category paginate with page (1-based). product, offers, seller and seller-products do not paginate at all — there is no page or cursor parameter on them.

Parameters

Search (/search)

Product (/product)

Reviews (/reviews)

Category (/category)

Offers (/offers)

Seller (/seller) and seller products (/seller-products)

Examples

import os, requests

BASE = "https://api.scavio.dev"
HEADERS = {"Authorization": f"Bearer {os.environ['SCAVIO_API_KEY']}"}

# 1. Search (1 credit on the default com domain)
results = requests.post(f"{BASE}/api/v1/walmart/search", headers=HEADERS,
    json={"query": "wireless headphones", "sort_by": "price_low", "max_price": 100}).json()

product_id = results["data"]["products"][0]["id"]   # search rows carry `id`, not `product_id`

# 2. Full product detail
product = requests.post(f"{BASE}/api/v1/walmart/product", headers=HEADERS,
    json={"product_id": product_id}).json()

# 3. Reviews, page 2 (10 per page)
reviews = requests.post(f"{BASE}/api/v1/walmart/reviews", headers=HEADERS,
    json={"product_id": product_id, "page": 2, "sort": "rating-desc"}).json()

# 4. Buy box for an item
offers = requests.post(f"{BASE}/api/v1/walmart/offers", headers=HEADERS,
    json={"product_id": "2979510112"}).json()

# 5. Seller storefront, then their catalog (numeric seller_catalog_id)
seller = requests.post(f"{BASE}/api/v1/walmart/seller", headers=HEADERS,
    json={"seller_id": "101480084"}).json()
catalog = requests.post(f"{BASE}/api/v1/walmart/seller-products", headers=HEADERS,
    json={"seller_id": "101480084"}).json()

# 6. Mexican marketplace search: this call costs 2 credits, not 1
mx = requests.post(f"{BASE}/api/v1/walmart/search", headers=HEADERS,
    json={"query": "audifonos", "domain": "com.mx"}).json()

Response

Every response uses the envelope { data, response_time, credits_used, credits_remaining }, plus an optional warnings[] array of strings that Walmart adds when the request used a retired parameter.

• search puts the rows in data.products[] with data.products_count, and reports the Walmart store the results were served against in data.location. category returns the same product shape as search.
• product returns price, rating, images, specifications, availability and seller.
• reviews returns the review bodies with ratings, text, author and date, plus the rating breakdown.
• offers returns price, seller, condition and the buy-box flag.
• seller returns store name, rating, review count, Pro Seller badge and business details.
• seller-products returns the seller's catalog with total_count.

Read credits_used on the response rather than assuming a cost, since search and category are body-priced.

Changed in 3.0.0

If you have an older version of this skill installed, stop sending these. They were tested against the live site before removal, and the API now answers them with a warnings[] entry rather than an error, which means a request that looks successful was silently unfiltered:

• device is gone. Desktop, mobile and tablet return identical page data, so the response would not change.
• delivery_zip is gone. Walmart mints its location cookies server-side and ignores any sent to it, so results always come back against its default store. The store actually used is reported in data.location.
• store_id is gone, for the same reason as delivery_zip. The store used is reported in data.location.
• fulfillment_speed: "2_days" is gone. It leaked items 3-4 days out.
• fulfillment_speed: "anytime" is gone. It was a no-op. To mean "anytime", omit the parameter entirely.

domain is NOT retired. It is live, it is the price-bearing parameter, and it is the only way to reach walmart.ca and walmart.com.mx.

New since 2.x: /reviews, /category, /offers, /seller and /seller-products. sort_by gained rating_high and new. search and product both changed response shape.

Guardrails

• Never fabricate product names, prices, item ids, ratings or availability. Only return data the API returned.
• /offers returns the BUY-BOX SELLER ONLY. It is not the full offer list, and must never be described as one. If the user wants every seller on an item, say that this API cannot enumerate them.
• /seller-products returns roughly the first 40 items, server-rendered. There is no pagination on it. total_count reports the seller's real catalog size, so the two numbers will disagree and that is expected. Do not invent a page parameter.
• seller_id must be the NUMERIC catalog seller id from seller_catalog_id. The GUID form of seller_id returns 404.
• domain is accepted on /search and /category only. walmart.ca product pages could not be fetched at all in testing, so the id-keyed endpoints are US-only.
• limit on /category trims the response after fetching. It does not reduce the credit cost.
• category_id accepts either the leaf id or the full underscore-joined path.
• sort_by, fulfillment_speed, fulfillment_type and domain are closed enums - a value outside them is a 400. Send only the values listed above; in particular fulfillment_speed no longer accepts 2_days or anytime, and to mean "anytime" you omit the parameter.
• Always include the product URL so the user can verify and complete the purchase.

Failure handling

• 400 means an invalid or missing parameter. Fix and retry.
• 401 means the API key is invalid or missing. Check SCAVIO_API_KEY.
• 404 on /seller or /seller-products almost always means a GUID was sent instead of the numeric seller_catalog_id.
• 429 means a rate or usage limit was exceeded. Wait before retrying. See https://scavio.dev/docs/rate-limits.
• 502 / 503 mean the upstream is temporarily unavailable. Transient 502s happen on Walmart; wait a few seconds and retry once before reporting failure.
• If a response carries warnings[], surface it to the user. It means part of their request was ignored.
• If search returns nothing, relax the filters (drop fulfillment_speed, widen min_price/max_price) and retry.
• If SCAVIO_API_KEY is not set, prompt the user to export it before continuing.

Docs

• Search: https://scavio.dev/docs/walmart-api
• Product: https://scavio.dev/docs/walmart-product
• Reviews: https://scavio.dev/docs/walmart-reviews
• Category: https://scavio.dev/docs/walmart-category
• Offers: https://scavio.dev/docs/walmart-offers
• Seller: https://scavio.dev/docs/walmart-seller
• Seller products: https://scavio.dev/docs/walmart-seller-products