# Walmart (/docs/walmart)



Walmart [#walmart]

Walmart keyword search, category browsing, product detail, customer reviews, and
marketplace seller offers behind the same unified envelope and canonical commerce schema
as Amazon and Google Shopping, so one parser handles all three.

Base URL: `/v1/walmart/...`

Getting started [#getting-started]

Every endpoint is a `GET` with query parameters and an `x-api-key` header, and every one
costs 5 credits. If you have a keyword, start at `search`. If you have a URL, the product
id is the number at the end of it:

```
https://www.walmart.com/ip/AirPods-Pro-3/17835006350
                                         ^^^^^^^^^^^
```

```bash
curl "https://www.socialcrawl.dev/v1/walmart/product?product_id=17835006350" \
  -H "x-api-key: $SOCIALCRAWL_API_KEY"
```

Walmart's alphanumeric catalog id (for example `34J2GQ9D9TFM`) works in the same
parameter, and every response returns both so you can join on whichever your system
already stores.

Endpoints [#endpoints]

<PlatformEndpoints platform="walmart" />

Typical flow [#typical-flow]

Start from a keyword and work down to detail:

```bash
# 1. Keyword to product ids, ~40 rows a page, prices included
curl "https://www.socialcrawl.dev/v1/walmart/search?query=airpods%20pro" \
  -H "x-api-key: $SOCIALCRAWL_API_KEY"

# 2. Full detail on one product
curl "https://www.socialcrawl.dev/v1/walmart/product?product_id=17835006350" \
  -H "x-api-key: $SOCIALCRAWL_API_KEY"

# 3. What shoppers wrote, up to 50 a page
curl "https://www.socialcrawl.dev/v1/walmart/reviews?product_id=17835006350&limit=50" \
  -H "x-api-key: $SOCIALCRAWL_API_KEY"

# 4. Who else sells it, and for how much
curl "https://www.socialcrawl.dev/v1/walmart/offers?product_id=17835006350" \
  -H "x-api-key: $SOCIALCRAWL_API_KEY"
```

`GET /v1/walmart/search` is the keyword-to-product-id resolver for the rest of the
platform: everything except `category` takes the `product_id` it returns. If you already
hold product ids, skip step 1.

Browsing rather than searching? `GET /v1/walmart/category?category_id=3944` walks a whole
category up to 100 products a call, which is the better shape for price monitoring across
a fixed set. Category ids appear in the category URLs on any product detail response.

Three things worth knowing before you build [#three-things-worth-knowing-before-you-build]

**Search rows carry prices, with a small null minority.** Most search results include
`price.current`, but a few in-stock rows come back with no price at all. Those report
`price.current` as `null` rather than a misleading `0`, so a `null` means "Walmart did not
publish one here", not "free". Call `GET /v1/walmart/product` with that row's id when you
need a guaranteed price.

**Category rows carry real prices, product rows carry more fields.** `category` returns
`price.current` and `price.original` on every row, which makes it the right source for
price monitoring across a product set. It does not populate `brand`, so read that from
`GET /v1/walmart/product` when you need it.

**Review pages can overlap.** When sorting by recency, consecutive pages occasionally
repeat a review, because Walmart's review feed shifts between calls. Every review
row carries a stable `id`, so de-duplicate by it when crawling. The `sort` parameter is a
hint rather than a guarantee — sort the rows yourself if order matters.

Store-level pricing [#store-level-pricing]

Walmart prices and stock genuinely vary by store. Both `search` and `category` accept
`zip_code`, `state`, or `store_id` to localise availability, pickup, and shipping options
to one location, which is the difference between a national list price and what a shopper
actually sees. They also share the same `min_price` / `max_price` / `sort_by` / `facet`
filters, so a filtered keyword search and a filtered category walk take identical
parameters.

```bash
curl "https://www.socialcrawl.dev/v1/walmart/search?query=airpods%20pro&zip_code=90210&max_price=200" \
  -H "x-api-key: $SOCIALCRAWL_API_KEY"
```

Marketplaces [#marketplaces]

Pass `country=US` (default, walmart.com) or `country=CA` (walmart.ca) on any endpoint.
Product ids are marketplace-specific, so an id from one will correctly return a
not-found against the other rather than resolving to the wrong product.

Response shape [#response-shape]

Products, reviews, and seller offers use the shared canonical commerce objects documented
under [Schema](/docs/schema.md). A Walmart product and an Amazon product have the same leaf
names, so a price-comparison integration needs one mapping, not one per retailer.

Walmart-specific extras ride on `ext`: `ext.catalog_id` carries the alphanumeric catalog
id, and `ext.seller_id` carries the seller identifier.

Notes [#notes]

* All endpoints use `GET` with query parameters
* Authentication via the `x-api-key` header
* Responses follow the unified SocialCrawl schema
* Empty results and not-found ids are refunded automatically and never billed
* Paginate with the universal `cursor` parameter until you receive an empty list; the
  upstream's own result counter is not a reliable total