Walmart API
The TrueScrape Walmart API exposes 4 public endpoints covering Browse a Walmart category, Walmart product details and Walmart product reviews. Every call is a GET against public, logged-out pages and returns the same unified schema as every other platform here. Calls cost 3 credits each. A cache hit is free, and a failed or empty response is never charged.
Endpoints
| Endpoint | Returns | Credits | Cacheable | Batchable |
|---|---|---|---|---|
| /v1/walmart/category | Browse a Walmart category | 3 | yes | yes |
| /v1/walmart/product | Walmart product details | 3 | yes | yes |
| /v1/walmart/reviews | Walmart product reviews | 3 | yes | yes |
| /v1/walmart/search | Search Walmart | 3 | yes | yes |
Reference
GET
/v1/walmart/category3 creditscacheablebatchableBrowse a Walmart category
Public Walmart category listing: the same shape as walmart.search, keyed by category id instead of a query.
| Parameter | Type | Required | Description |
|---|---|---|---|
| category | string | yes | Walmart category id, e.g. "3944_1089430_37807" |
| tld | string | no | Walmart marketplace, default com. One of: com, ca |
| country_code | string | no | — |
| page | number | no | — |
Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).
Returns an object with items, meta.
Fields
| Field | Type | Present |
|---|---|---|
| items | SearchResultItem[] | always |
| meta | object | always |
| meta.page | number | always |
| meta.pages | number | null | always |
curl
curl "$API/v1/walmart/category?category=%3Ccategory%3E&cache_max_age=7d" \
-H "x-api-key: $KEY"TypeScript
const query = new URLSearchParams({
category: '<category>',
cache_max_age: '7d',
});
const response = await fetch(`${API}/v1/walmart/category?${query}`, {
headers: { 'x-api-key': KEY },
});
const body = await response.json();
if (!body.success) throw new Error(body.error.code);
// 3 credits, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);Python
Python
import os, httpx
r = httpx.get(
f"{os.environ['API']}/v1/walmart/category",
params={
"category": "<category>",
"cache_max_age": "7d",
},
headers={"x-api-key": os.environ["KEY"]},
timeout=30,
)
body = r.json()
if not body["success"]:
raise RuntimeError(body["error"]["code"])
print(body["data"], body["meta"]["creditsCharged"])Response codes
| 200 | Success |
| 400 | invalid_request. Not charged |
| 401 | missing_api_key / invalid_api_key / revoked_api_key. Never a billing error |
| 402 | insufficient_credits. The key is valid, the balance is not |
| 429 | daily_cap_exceeded or upstream_rate_limited. Not charged |
| 501 | not_configured. This deployment is not set up to serve this endpoint. Not charged. |
| 502 | upstream_blocked / upstream_schema_drift. Not charged |
| 504 | upstream_timeout. Not charged |
GET
/v1/walmart/product3 creditscacheablebatchableWalmart product details
Public details for a Walmart listing: title, price, availability, seller, ratings, images and specifications, read from the page's own __NEXT_DATA__ payload.
| Parameter | Type | Required | Description |
|---|---|---|---|
| product_id | string | yes | Numeric Walmart item id, the last path segment of an /ip/ URL, e.g. 18210919718 |
| tld | string | no | Walmart marketplace, default com. One of: com, ca |
| country_code | string | no | — |
Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).
Returns one Product.
Fields
| Field | Type | Present | Description |
|---|---|---|---|
| platform | one of 32 strings | always | |
| id | string | always | The product id on its marketplace: the ASIN on Amazon, the item id on Walmart and eBay. Always a string. |
| title | string | null | always | |
| brand | string | null | always | |
| description | string | null | always | |
| url | string | null | always | |
| imageUrls | string[] | always | |
| price | number | null | always | The price a buyer pays now, in `currency`. |
| currency | string | null | always | ISO 4217 currency code for the amounts in this record, such as USD or EUR. |
| listPrice | number | null | always | The struck-through reference price shown next to `price` when the listing shows a discount. |
| availability | in_stock | out_of_stock | preorder | discontinued | unknown | null | always | Stock status. `unknown` means the listing showed a status that could not be read as one of the other values. |
| rating | number | null | always | Average customer rating, out of 5. |
| reviewCount | number | null | always | Number of ratings or reviews the marketplace reports for the product, not the number of entries in `reviews`. |
| sellerName | string | null | always | |
| shipsFrom | string | null | always | The party the item ships from, as the listing names it. |
| marketplace | string | null | always | The marketplace site this product was read from, such as `amazon.co.uk`. |
| categories | string[] | always | Category breadcrumb, from the broadest category to the most specific. |
| featureBullets | string[] | always | |
| attributes | Record<string, string> | always | Specifications as label and value pairs. Which labels appear varies by marketplace and category. |
| reviews | ProductReview[] | always | A sample of reviews shown on the product page, not the full review list. |
| fetchedAt | string | always | When this record was retrieved, as an ISO 8601 timestamp. |
curl
curl "$API/v1/walmart/product?product_id=%3Cproduct_id%3E&cache_max_age=7d" \
-H "x-api-key: $KEY"TypeScript
const query = new URLSearchParams({
product_id: '<product_id>',
cache_max_age: '7d',
});
const response = await fetch(`${API}/v1/walmart/product?${query}`, {
headers: { 'x-api-key': KEY },
});
const body = await response.json();
if (!body.success) throw new Error(body.error.code);
// 3 credits, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);Python
Python
import os, httpx
r = httpx.get(
f"{os.environ['API']}/v1/walmart/product",
params={
"product_id": "<product_id>",
"cache_max_age": "7d",
},
headers={"x-api-key": os.environ["KEY"]},
timeout=30,
)
body = r.json()
if not body["success"]:
raise RuntimeError(body["error"]["code"])
print(body["data"], body["meta"]["creditsCharged"])Response codes
| 200 | Success |
| 400 | invalid_request. Not charged |
| 401 | missing_api_key / invalid_api_key / revoked_api_key. Never a billing error |
| 402 | insufficient_credits. The key is valid, the balance is not |
| 429 | daily_cap_exceeded or upstream_rate_limited. Not charged |
| 501 | not_configured. This deployment is not set up to serve this endpoint. Not charged. |
| 502 | upstream_blocked / upstream_schema_drift. Not charged |
| 504 | upstream_timeout. Not charged |
GET
/v1/walmart/reviews3 creditscacheablebatchableWalmart product reviews
Paginated customer reviews for a Walmart product, from its dedicated reviews page.
| Parameter | Type | Required | Description |
|---|---|---|---|
| product_id | string | yes | Numeric Walmart item id, e.g. 18210919718 |
| tld | string | no | Walmart marketplace, default com. One of: com, ca |
| country_code | string | no | — |
| page | number | no | — |
| sort | relevancy | helpful | submission-desc | submission-asc | rating-desc | rating-asc | no | — |
| ratings | string | no | Comma list of star ratings to include, e.g. "5,4" |
| verified_purchase | boolean | no | — |
Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).
Returns an object with items, productName, productUrl, rating, reviewCount.
Fields
| Field | Type | Present |
|---|---|---|
| items | ProductReview[] | always |
| productName | string | null | always |
| productUrl | string | null | always |
| rating | number | null | always |
| reviewCount | number | null | always |
curl
curl "$API/v1/walmart/reviews?product_id=%3Cproduct_id%3E&cache_max_age=7d" \
-H "x-api-key: $KEY"TypeScript
const query = new URLSearchParams({
product_id: '<product_id>',
cache_max_age: '7d',
});
const response = await fetch(`${API}/v1/walmart/reviews?${query}`, {
headers: { 'x-api-key': KEY },
});
const body = await response.json();
if (!body.success) throw new Error(body.error.code);
// 3 credits, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);Python
Python
import os, httpx
r = httpx.get(
f"{os.environ['API']}/v1/walmart/reviews",
params={
"product_id": "<product_id>",
"cache_max_age": "7d",
},
headers={"x-api-key": os.environ["KEY"]},
timeout=30,
)
body = r.json()
if not body["success"]:
raise RuntimeError(body["error"]["code"])
print(body["data"], body["meta"]["creditsCharged"])Response codes
| 200 | Success |
| 400 | invalid_request. Not charged |
| 401 | missing_api_key / invalid_api_key / revoked_api_key. Never a billing error |
| 402 | insufficient_credits. The key is valid, the balance is not |
| 429 | daily_cap_exceeded or upstream_rate_limited. Not charged |
| 501 | not_configured. This deployment is not set up to serve this endpoint. Not charged. |
| 502 | upstream_blocked / upstream_schema_drift. Not charged |
| 504 | upstream_timeout. Not charged |
GET
/v1/walmart/search3 creditscacheablebatchableSearch Walmart
Public Walmart search results for a query: position, price, rating and availability per item.
| Parameter | Type | Required | Description |
|---|---|---|---|
| query | string | yes | Search terms, e.g. "laptop" |
| tld | string | no | Walmart marketplace, default com. One of: com, ca |
| country_code | string | no | — |
| page | number | no | — |
Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).
Returns an object with items, meta.
Fields
| Field | Type | Present |
|---|---|---|
| items | SearchResultItem[] | always |
| meta | object | always |
| meta.page | number | always |
| meta.pages | number | null | always |
curl
curl "$API/v1/walmart/search?query=ai%20agents&cache_max_age=7d" \
-H "x-api-key: $KEY"TypeScript
const query = new URLSearchParams({
query: 'ai agents',
cache_max_age: '7d',
});
const response = await fetch(`${API}/v1/walmart/search?${query}`, {
headers: { 'x-api-key': KEY },
});
const body = await response.json();
if (!body.success) throw new Error(body.error.code);
// 3 credits, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);Python
Python
import os, httpx
r = httpx.get(
f"{os.environ['API']}/v1/walmart/search",
params={
"query": "ai agents",
"cache_max_age": "7d",
},
headers={"x-api-key": os.environ["KEY"]},
timeout=30,
)
body = r.json()
if not body["success"]:
raise RuntimeError(body["error"]["code"])
print(body["data"], body["meta"]["creditsCharged"])Response codes
| 200 | Success |
| 400 | invalid_request. Not charged |
| 401 | missing_api_key / invalid_api_key / revoked_api_key. Never a billing error |
| 402 | insufficient_credits. The key is valid, the balance is not |
| 429 | daily_cap_exceeded or upstream_rate_limited. Not charged |
| 501 | not_configured. This deployment is not set up to serve this endpoint. Not charged. |
| 502 | upstream_blocked / upstream_schema_drift. Not charged |
| 504 | upstream_timeout. Not charged |
Questions
- How much does the Walmart API cost?
- Calls cost 3 credits each. Every endpoint is cacheable, and a cache hit costs nothing. A failed request and an empty result are both free, on every endpoint.
- Does the Walmart API need a login or cookies?
- No. Every endpoint reads public, logged-out pages only — no account, no cookies, no session. An API key identifies your own TrueScrape account and nothing else.
- Can I fetch many Walmart targets in one request?
- Yes. 4 of 4 are batchable: one POST to /v1/jobs/batch takes many targets and returns a job id to poll.
- Can I watch Walmart endpoints for changes?
- Yes, 2 of 4. A subscription polls on your schedule and fires your webhook only when the content changed; the rest carry x-subscribable: false in the spec.