Call this endpoint to return restock recommendations for your WFS items with optional demand and insight filters. You can use this API to identify WFS items that are at risk of going out of stock or are already out of stock.

Use Restock Recommendations to get Walmart-generated suggestions for the items you should restock with WFS based on your current inventory and forecasted sales demand. These suggestions are available on demand.

It provides suggested replenishment quantities, days of supply, and opportunity estimates. Key attributes include:

suggestedUnits: The number of units we suggest you send of this item to WFS
forecastedSalesLift: The estimated increase in sales you may see if your items are restocked according to our suggestions
totalForecastedSalesLost: How much money you're estimated to lose out on if you don't restock your inventory

Once you determine which suggested items to restock, you can use the Create inbound shipment API to create a shipping plan to send inventory to WFS.

This page describes an example using only the required parameters and inputs for retrieving restock recommendations. For a full list of customization options and additional capabilities, refer to the Walmart Recommendations API Reference.

Endpoint

GET https://marketplace.walmartapis.com/v3/wfs/recommendation/restock

Retrieve restock recommendations for the first 30 SKUs

Sample request

Use this sample request to retrieve restock recommendations for the first 30 SKUs. Note that there are no insights or filters used in this request.

curl "https://marketplace.walmartapis.com/v3/wfs/recommendation/restock" \ -H "WM_QOS.CORRELATION_ID: b3261d2d-028a-4ef7-8602-633c23200af6" \ -H "WM_MARKET: US" \ -H "WM_SVC.NAME: Walmart Marketplace" \ -H "WM_SEC.ACCESS_TOKEN: eyJraWQiOiIzZjVhYTFmNS1hYWE5LTQzM....." \ -H "WM_GLOBAL_VERSION: 3.1" \ -H "Accept: application/json"

import requests url = "https://marketplace.walmartapis.com/v3/wfs/recommendation/restock"
headers = { "WM_QOS.CORRELATION_ID": "b3261d2d-028a-4ef7-8602-633c23200af6", "WM_MARKET": "US", "WM_SVC.NAME": "Walmart Marketplace", "WM_SEC.ACCESS_TOKEN": "<ACCESS_TOKEN>", "WM_GLOBAL_VERSION": "3.1", "Accept": "application/json",
} response = requests.get(url, headers=headers, timeout=30)
response.raise_for_status()
print(response.json())

Sample response

{ "status": "OK", "payload": { "recommendedItems": [ { "gtin": "00673419391276", "sku": "MVSSS09", "itemId": "5014162878", "brand": "LEGO", "itemName": "LEGO Spring Festival Auspicious Dragon Buildable Figure, Educational Toy for Kids, Dragon Toy Building Set, Great Spring Festival Decoration or Unique Gift for Boys and Girls Ages 10 and Up, 80112", "stockStatus": "At Risk", "itemCondition": "New", "insights": { "daysOfSupply": 0, "suggestedUnits": 11, "forecastedSalesLift": 857.89, "customerFavorite": true } }, { "gtin": "00767461241013", "sku": "W-YHB-5060P Black", "itemId": "3285483773", "brand": "Ocuuziisu", "itemName": "Ocuuziisu 50\" × 60\" Heated Throw Blanket — 9 Heat Levels, 1–10H Timer, Fast Even Warming Electric Blanket Throw, Machine Washable — Green & Gray", "stockStatus": "At Risk", "itemCondition": "New", "insights": { "daysOfSupply": 2, "suggestedUnits": 56, "forecastedSalesLift": 16.81, "customerFavorite": true } } ], "totalInsights": { "totalForecastedSalesLost": 0, "totalForecastedSalesAtRisk": 17, "totalEstimatedSalesLift": 17 }, "totalRecords": 2 }
}

Retrieve recommendations using insights

Sample request

Use this sample request to retrieve restock recommendations for at risk Gross Merchandise Value (GMV) and lost sales.

curl "https://marketplace.walmartapis.com/v3/wfs/recommendation/restock?showInsights=true" \ -H "WM_QOS.CORRELATION_ID: b3261d2d-028a-4ef7-8602-633c23200af6" \ -H "WM_MARKET: US" \ -H "WM_SVC.NAME: Walmart Marketplace" \ -H "WM_SEC.ACCESS_TOKEN: eyJraWQiOiIzZjVhYTFmNS1hYWE5LTQzM....." \ -H "WM_GLOBAL_VERSION: 3.1" \ -H "Accept: application/json"

import requests url = "https://marketplace.walmartapis.com/v3/wfs/recommendation/restock"
params = {"showInsights": "true"}
headers = { "WM_QOS.CORRELATION_ID": "b3261d2d-028a-4ef7-8602-633c23200af6", "WM_MARKET": "US", "WM_SVC.NAME": "Walmart Marketplace", "WM_SEC.ACCESS_TOKEN": "<ACCESS_TOKEN>", "WM_GLOBAL_VERSION": "3.1", "Accept": "application/json",
} response = requests.get(url, headers=headers, params=params, timeout=30)
response.raise_for_status()
print(response.json())

Sample response

{ "status": "OK", "payload": { "recommendedItems": [ { "gtin": "00673419391276", "sku": "MVSSS09", "itemId": "5014162878", "brand": "LEGO", "itemName": "LEGO Spring Festival Auspicious Dragon Buildable Figure, Educational Toy for Kids, Dragon Toy Building Set, Great Spring Festival Decoration or Unique Gift for Boys and Girls Ages 10 and Up, 80112", "stockStatus": "At Risk", "itemCondition": "New", "insights": { "daysOfSupply": 0, "suggestedUnits": 11, "forecastedSalesLift": 857.89, "customerFavorite": true } }, { "gtin": "00767461241013", "sku": "W-YHB-5060P Black", "itemId": "3285483773", "brand": "Ocuuziisu", "itemName": "Ocuuziisu 50\" × 60\" Heated Throw Blanket — 9 Heat Levels, 1–10H Timer, Fast Even Warming Electric Blanket Throw, Machine Washable — Green & Gray", "stockStatus": "At Risk", "itemCondition": "New", "insights": { "daysOfSupply": 2, "suggestedUnits": 56, "forecastedSalesLift": 16.81, "customerFavorite": true } } ], "totalInsights": { "totalForecastedSalesLost": 0, "totalForecastedSalesAtRisk": 17, "totalEstimatedSalesLift": 17 }, "totalRecords": 2 }
}

Retrieve customer favorites only

Sample request

Use this sample request to retrieve restock recommendations for customer favorites.

curl "https://marketplace.walmartapis.com/v3/wfs/recommendation/restock?isInDemand=true" \ -H "WM_QOS.CORRELATION_ID: b3261d2d-028a-4ef7-8602-633c23200af6" \ -H "WM_MARKET: US" \ -H "WM_SVC.NAME: Walmart Marketplace" \ -H "WM_SEC.ACCESS_TOKEN: eyJraWQiOiIzZjVhYTFmNS1hYWE5LTQzM....." \ -H "WM_GLOBAL_VERSION: 3.1" \ -H "Accept: application/json"

import requests url = "https://marketplace.walmartapis.com/v3/wfs/recommendation/restock"
params = {"isInDemand": "true"}
headers = { "Accept": "application/json", "Content-Type": "application/json", "WM_MARKET": "US", "WM_GLOBAL_VERSION": "3.1", "wm_audit.origin_source": "SELLER_API",
} response = requests.get(url, headers=headers, params=params, timeout=30)
response.raise_for_status()
print(response.json())

Sample response

{ "status": "OK", "payload": { "recommendedItems": [ { "gtin": "00673419391276", "sku": "MVSSS09", "itemId": "5014162878", "brand": "LEGO", "itemName": "LEGO Spring Festival Auspicious Dragon Buildable Figure, Educational Toy for Kids, Dragon Toy Building Set, Great Spring Festival Decoration or Unique Gift for Boys and Girls Ages 10 and Up, 80112", "stockStatus": "At Risk", "itemCondition": "New", "insights": { "daysOfSupply": 0, "suggestedUnits": 11, "forecastedSalesLift": 857.89, "customerFavorite": true } } ], "totalInsights": { "totalForecastedSalesLost": 0, "totalForecastedSalesAtRisk": 17, "totalEstimatedSalesLift": 17 }, "totalRecords": 1 }
}

Modify your code

Replace all placeholder values with your actual shipment data before making the API request.

WM_QOS.CORRELATION_ID - Use a unique correlation UUID to track the request.
WM_SEC.ACCESS_TOKEN - Replace with your valid access token obtained through authentication.

Result

If successful, the API returns 200 OK with a JSON body containing status and payload. The payload includes a list of recommended replenishments with fields such as itemId, gtin, vendorSku, and recommendedReplenishmentQty.

When showInsights=true, the response also includes aggregate metrics under payload.insights, including outOfStockLostSales, atRiskGMV, and totalSalesOpportunityAmount.

If the API returns 400 Bad Request, one or more inputs are invalid. For example, non-boolean values are present for isInDemand or the limit is out of range.