Skip to content

Walmart API

This reference covers two HTTP endpoints for retrieving Walmart data in real time: a search endpoint that returns a results page with products and facets, and a product endpoint that returns structured details for one item. Both are authenticated with a Bearer token and both accept localization and rendering controls. The sections below describe each parameter, show the response shape, and explain how credits are charged.

Overview

The API exposes two endpoints. The search endpoint at /api/v1/walmart/search returns Walmart search results. The product endpoint at /api/v1/walmart/product returns structured details for a single product. Both are GET requests authenticated with an API key. A Postman collection covering the broader feature set is also available for exploring the API interactively.

Walmart Search API

The search endpoint takes a required query string and returns a JSON document containing metadata, a list of products, facet counts and the location context used. Two inputs are mandatory: your API key and the search query. Everything else is optional and changes which results come back or how they are rendered.

Search quick start

Send a GET request to /api/v1/walmart/search with the query parameter and an Authorization: Bearer YOUR-API-KEY header. The example below uses query=iphone. The same request can be expressed in cURL, Python, Node.js, Java, Ruby, PHP or Go, and the CLI offers a walmart-search command.

Search parameters

The table below lists every parameter accepted by the search endpoint, with its type, default and purpose. Use it as a control map: required inputs first, then rendering controls, then filters, then localization and labeling.

Search response

A successful search returns JSON with four top-level keys. meta_data carries the resolved Walmart URL, the total number of results, the number of products on the page, the current page and the total page count. products is an array of product objects with position, product ID, title, price, currency, rating, review count, availability, image, URL, brand, seller and shipping flags. facets groups counts by brand, price range and star rating. location echoes the ZIP code and store ID used for localization, or null when neither was supplied. The example below uses query=iphone and shows one product entry plus truncated facet arrays.

Search credit cost and retries

A successful search costs 10 API credits when light requests are enabled, which is the default. Setting light_request=false forces JavaScript rendering and raises the cost to 15 credits. A failed search is retried for up to 30 seconds before the call returns, so client code should allow for that maximum wait rather than assuming an immediate failure.

Search API key

Every request is authenticated with your private API key, sent as a Bearer token in the Authorization header. To obtain a key, create an account and confirm your email address. The authentication documentation also covers the deprecated api_key query parameter.

Search light request

Light requests return a quick response without JavaScript rendering and cost 10 credits instead of 15. Because no browser is used, a light request may return less data than a regular request. To force JavaScript rendering, add light_request=false to the request.

Search screenshot

Setting screenshot=true captures a visual snapshot of the search page as a browser would render it. Screenshot requests always use a full browser environment, so all JavaScript and dynamic content is loaded before capture. Each screenshot request costs 15 API credits and ignores the light_request setting even when it is true. The image is returned as a base64-encoded string that you decode and save as an image file.

Search start page

start_page selects which page of Walmart search results to scrape. The default is 1 for the first page; use 2 for the second page and so on. The example below requests page 3.

Search query

query is the text you would type into Walmart.com and is required for the search endpoint. URL-encode the value before sending it, especially when it contains special characters. The source provides encoding snippets for cURL, Python, Node.js, Java, Ruby, PHP and Go.

Search minimum price

min_price filters results to products at or above a price. For example, min_price=50 shows only products priced $50 or higher. The parameter is an integer with an empty default.

Search maximum price

max_price filters results to products at or below a price. For example, max_price=200 shows only products priced $200 or lower. The parameter is an integer with an empty default.

Search sort by

sort_by orders the results. best_match is the default and follows Walmart's relevance ranking. price_low sorts price ascending, price_high sorts price descending, and best_seller returns best sellers. For example, sort_by=price_low.

Search device

device sets the device type for the request and accepts desktop, mobile or tablet. The default is desktop. Mobile results may differ in layout and in which products are available, so choose the device that matches the experience you are measuring.

Search domain

domain specifies a Walmart domain for localization and lets you target a specific regional Walmart site. The default is an empty string. The example uses domain=com.

Search fulfillment speed

fulfillment_speed filters by delivery speed. today means same-day delivery, tomorrow means next-day delivery, 2_days means two-day delivery, and anytime means any delivery speed. The default is an empty string.

Search fulfillment type

fulfillment_type filters by fulfillment method. The only listed value is in_store, which restricts results to items available for in-store pickup. The default is an empty string.

Search delivery ZIP

delivery_zip returns results for a specific ZIP code area. The example uses delivery_zip=10001. The default is an empty string.

Search store ID

store_id returns results for a specific Walmart store. The example uses store_id=3520. A list of Walmart store IDs is available as a downloadable JSON file. The default is an empty string.

Search full HTML

add_html includes the full HTML of the page in the response. It defaults to false; pass add_html=true to include the HTML.

Search tag

tag attaches a custom string identifier to a request. The value is returned with the response headers. It is optional and does not affect scraping behavior.

Walmart Product API

The product endpoint returns structured details for one item. It requires a product ID and an API key. The response includes pricing, availability, images, specifications, ratings and seller information.

Product quick start

Send a GET request to /api/v1/walmart/product with product_id=5491199371 and the Bearer token header. The same request can be expressed in cURL, Python, Node.js, Java, Ruby, PHP or Go, and the CLI offers a walmart-product command.

Product parameters

The product endpoint accepts a smaller set of parameters than the search endpoint. The required inputs are the API key and the product ID. The remaining controls cover rendering, localization and labeling.

Product response

The product response is a single JSON object. product_id and title identify the item. description holds the product description. price contains current, original, currency and discount percentage. availability contains in-stock status, quantity and delivery options for standard, express and pickup. images is an array of image URLs. specifications holds brand, model, storage, color and other attributes. rating contains the average, count and a distribution by star level. seller contains name, ID and rating. shipping contains free, price and two-day flags. The example below uses product 5491199371.

Product API key

Authentication works the same way as on the search endpoint: send your private API key as a Bearer token in the Authorization header. Account creation and email confirmation are required to obtain a key, and the authentication documentation covers the deprecated api_key query parameter.

Product light request

Light requests skip JavaScript rendering, return faster and cost 10 credits instead of 15. They may return less data than a regular request. Set light_request=false to force JavaScript rendering.

Product screenshot

screenshot=true captures the product page as a browser would render it. Screenshot requests always use a full browser environment and cost 15 API credits. They ignore light_request even when it is true. The image is returned as a base64-encoded string.

Product ID

product_id is the unique Walmart product identifier and is required for the product endpoint. It appears at the end of a Walmart product URL. For example, in https://www.walmart.com/ip/Apple-iPhone-15-Pro-Max-256GB/5491199371 the product ID is 5491199371.

Product domain

domain specifies a Walmart domain for localization and lets you target a specific regional Walmart site. The default is an empty string. The example uses domain=com.

Product device

device sets the device type and accepts desktop, mobile or tablet. The default is desktop. Mobile results may differ in layout and available products.

Product delivery ZIP

delivery_zip returns product results for a specific ZIP code area. The example uses delivery_zip=10001. The default is an empty string.

Product store ID

store_id returns product results for a specific Walmart store. The example uses store_id=3520. A list of Walmart store IDs is available as a downloadable JSON file. The default is an empty string.

Product full HTML

add_html includes the full HTML of the product page in the response. It defaults to false; pass add_html=true to include the HTML.

Product tag

tag attaches a custom string identifier to a request. The value is returned with the response headers. It is optional and does not affect scraping behavior.

Credit cost for your requests

Each plan provides a monthly allotment of API credits. A Walmart API request costs either 10 or 15 credits depending on the request type. The table below reproduces the published breakdown: light requests default to 10 credits, and regular requests with JavaScript rendering cost 15 credits. Screenshot requests also cost 15 credits and override the light-request setting.

Credit cost by request type
Feature usedAPI credit cost
Light Requests (default)10
Regular requests (with JavaScript rendering)15

Screenshot requests also cost 15 credits and ignore the light_request setting.

Frequently asked questions

What is the difference between the search and product endpoints?

The search endpoint at /api/v1/walmart/search returns a page of Walmart search results with metadata, product summaries, facet counts and location context. The product endpoint at /api/v1/walmart/product returns structured details for a single item identified by product_id, including pricing, availability, images, specifications, ratings and seller information.

How many credits does a Walmart API request cost?

A light request costs 10 API credits. A regular request with JavaScript rendering costs 15 credits. A screenshot request also costs 15 credits and ignores the light_request setting.

What happens if a search request fails?

A failed search is retried for up to 30 seconds before the call returns. Client code should allow for that maximum wait rather than assuming an immediate failure.

How do I find a Walmart product ID?

The product ID is the number at the end of a Walmart product URL. For example, in https://www.walmart.com/ip/Apple-iPhone-15-Pro-Max-256GB/5491199371 the product ID is 5491199371.

Can I localize results by ZIP code or store?

Yes. Both endpoints accept delivery_zip and store_id. The search endpoint also accepts domain, fulfillment_speed and fulfillment_type for further localization and filtering.

Why might a light request return less data?

Light requests skip the browser environment, so they return faster and cost fewer credits but may not include all the data a regular JavaScript-rendered request would return. Set light_request=false to force rendering.

curl "{{APP_BASE_URL}}/api/v1/walmart/search?query=iphone" \
     -H 'Authorization: Bearer YOUR-API-KEY'
{
  "meta_data": {
    "url": "https://www.walmart.com/search?q=iphone",
    "number_of_results": 1000,
    "number_of_products": 40,
    "page": 1,
    "total_pages": 25
  },
  "products": [
    {
      "position": 1,
      "product_id": "5491199371",
      "title": "Apple iPhone 15 Pro Max, 256GB, Natural Titanium - Unlocked (Renewed Premium)",
      "price": 1099.99,
      "currency": "USD",
      "rating": 4.7,
      "review_count": 892,
      "availability": "In stock",
      "image": "https://i5.walmartimages.com/seo/...",
      "url": "https://www.walmart.com/ip/Apple-iPhone-15-Pro-Max-256GB/5491199371",
      "brand": "Apple",
      "seller": "Walmart",
      "prime": false,
      "free_shipping": true,
      "two_day_shipping": true
    },
    ...
  ],
  "facets": {
    "brands": [
      {"name": "Apple", "count": 245},
      {"name": "Samsung", "count": 189},
      ...
    ],
    "price_ranges": [
      {"min": 0, "max": 50, "count": 120},
      {"min": 50, "max": 100, "count": 85},
      ...
    ],
    "ratings": [
      {"stars": 4, "count": 350},
      {"stars": 3, "count": 125},
      ...
    ]
  },
  "location": {
    "zip_code": null,
    "store_id": null
  }
}
curl "{{APP_BASE_URL}}/api/v1/walmart/search?light_request=False&query=iphone" \
     -H "Authorization: Bearer YOUR-API-KEY"
curl "{{APP_BASE_URL}}/api/v1/walmart/search?query=iphone&screenshot=True" \
     -H "Authorization: Bearer YOUR-API-KEY"
curl "{{APP_BASE_URL}}/api/v1/walmart/search?query=iphone&start_page=3" \
     -H "Authorization: Bearer YOUR-API-KEY"
curl "{{APP_BASE_URL}}/api/v1/walmart/search?min_price=50&query=iphone" \
     -H "Authorization: Bearer YOUR-API-KEY"
curl "{{APP_BASE_URL}}/api/v1/walmart/search?max_price=50&query=iphone" \
     -H "Authorization: Bearer YOUR-API-KEY"
curl "{{APP_BASE_URL}}/api/v1/walmart/search?query=iphone&sort_by=price_low" \
     -H "Authorization: Bearer YOUR-API-KEY"
curl "{{APP_BASE_URL}}/api/v1/walmart/search?device=mobile&query=iphone" \
     -H "Authorization: Bearer YOUR-API-KEY"
curl "{{APP_BASE_URL}}/api/v1/walmart/search?domain=com&query=iphone" \
     -H "Authorization: Bearer YOUR-API-KEY"
curl "{{APP_BASE_URL}}/api/v1/walmart/search?fulfillment_speed=today&query=iphone" \
     -H "Authorization: Bearer YOUR-API-KEY"
curl "{{APP_BASE_URL}}/api/v1/walmart/search?fulfillment_type=in_store&query=iphone" \
     -H "Authorization: Bearer YOUR-API-KEY"
curl "{{APP_BASE_URL}}/api/v1/walmart/search?delivery_zip=10001&query=iphone" \
     -H "Authorization: Bearer YOUR-API-KEY"
curl "{{APP_BASE_URL}}/api/v1/walmart/search?query=iphone&store_id=3520" \
     -H "Authorization: Bearer YOUR-API-KEY"
curl "{{APP_BASE_URL}}/api/v1/walmart/search?add_html=true&query=iphone" \
     -H "Authorization: Bearer YOUR-API-KEY"
curl "{{APP_BASE_URL}}/api/v1/walmart/search?query=iphone&tag=your+text" \
     -H "Authorization: Bearer YOUR-API-KEY"
curl "{{APP_BASE_URL}}/api/v1/walmart/product?product_id=5491199371" \
     -H 'Authorization: Bearer YOUR-API-KEY'
{
  "product_id": "5491199371",
  "title": "Apple iPhone 15 Pro Max, 256GB, Natural Titanium - Unlocked (Renewed Premium)",
  "description": "Example post details.",
  "price": {
    "current": 1099.99,
    "original": 1299.99,
    "currency": "USD",
    "discount_percentage": 15.4
  },
  "availability": {
    "in_stock": true,
    "quantity": null,
    "delivery_options": {
      "standard": "3-5 business days",
      "express": "1-2 business days",
      "pickup": "Available today"
    }
  },
  "images": [
    "https://i5.walmartimages.com/seo/image1.jpg",
    "https://i5.walmartimages.com/seo/image2.jpg",
    ...
  ],
  "specifications": {
    "brand": "Apple",
    "model": "iPhone 15 Pro Max",
    "storage": "256GB",
    "color": "Natural Titanium",
    ...
  },
  "rating": {
    "average": 4.7,
    "count": 892,
    "distribution": {
      "5": 645,
      "4": 180,
      "3": 45,
      "2": 15,
      "1": 7
    }
  },
  "seller": {
    "name": "Walmart",
    "id": "walmart",
    "rating": null
  },
  "shipping": {
    "free": true,
    "price": 0,
    "two_day": true
  }
}
curl "{{APP_BASE_URL}}/api/v1/walmart/product?light_request=False&product_id=5491199371" \
     -H "Authorization: Bearer YOUR-API-KEY"
curl "{{APP_BASE_URL}}/api/v1/walmart/product?product_id=5491199371&screenshot=True" \
     -H "Authorization: Bearer YOUR-API-KEY"
curl "{{APP_BASE_URL}}/api/v1/walmart/product?product_id=5491199371" \
     -H "Authorization: Bearer YOUR-API-KEY"
curl "{{APP_BASE_URL}}/api/v1/walmart/product?domain=com&product_id=5491199371" \
     -H "Authorization: Bearer YOUR-API-KEY"
curl "{{APP_BASE_URL}}/api/v1/walmart/product?device=mobile&product_id=5491199371" \
     -H "Authorization: Bearer YOUR-API-KEY"
curl "{{APP_BASE_URL}}/api/v1/walmart/product?delivery_zip=10001&product_id=5491199371" \
     -H "Authorization: Bearer YOUR-API-KEY"
curl "{{APP_BASE_URL}}/api/v1/walmart/product?product_id=5491199371&store_id=3520" \
     -H "Authorization: Bearer YOUR-API-KEY"
curl "{{APP_BASE_URL}}/api/v1/walmart/product?add_html=true&product_id=5491199371" \
     -H "Authorization: Bearer YOUR-API-KEY"
curl "{{APP_BASE_URL}}/api/v1/walmart/product?product_id=5491199371&tag=your+text" \
     -H "Authorization: Bearer YOUR-API-KEY"
Feature usedAPI credit cost
Light Requests learn more (default)10
Regular requests (with JavaScript rendering)15