# Walmart (/docs/walmart)



Walmart [#walmart]

Walmart product, review, and marketplace-offer data 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. Start from a
product id, which is the number in any Walmart product URL:

```
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]

Most integrations chain two calls:

1. `GET /v1/walmart/search?query=airpods+pro` to turn a keyword into product ids.
2. `GET /v1/walmart/product?product_id=...` for the price and full detail, or
   `GET /v1/walmart/reviews?product_id=...&limit=50` for customer reviews.

For price monitoring across a whole product set, `GET /v1/walmart/category` is the better
starting point: it returns real prices where search does not.

Two things worth knowing before you build [#two-things-worth-knowing-before-you-build]

**Search does not return prices.** Walmart's search surface does not expose them, so the
`price.current` field on search results is `null` rather than a misleading `0`. Treat
search as the keyword-to-product-id resolver and read prices from `/v1/walmart/product`
or `/v1/walmart/category`.

**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.

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

Walmart prices and stock genuinely vary by store. `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.

```bash
curl "https://www.socialcrawl.dev/v1/walmart/search?query=milk&zip_code=90210" \
  -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). 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