Insights

To grow your business, you can use Insights API to learn actionable information critical to building your business and catalog offerings.

With the Insights API you can learn actionable information about your current listings: Top trending items, unpublished items, and quality of item listings.

You can programmatically do many of the tasks in the Seller Center’s Analytics areas such as Assortment Growth, exploring item best sellers by department and category, and view your unpublished items with the Insights APIs. To learn more about Growth Opportunities, see Analytics and Reports Dashboards in the Seller Center.

Top Trending Items API

You can look at what items are current best sellers on Walmart.com. Use the Trending Items API to generate a list of trending items to add them to your offerings, and use the Utilities APIs to locate the department and category IDs.

Use the Trending Items API and Utilities APIs to discover what items are currently trending best sellers at Walmart. Find out top selling item in each department or department category, and find out top selling items at Walmart during the holiday season.

• Get all Departments API – Locate all Department names and Department IDs.
• Get all Categories API – Locate all Category Names and Category IDs within a department.
• Get Trending Items API – Specify DepartmentID to get top selling items in that department.

Unpublished Items API

Get insights into why your items are getting unpublished with Unpublished Items APIs. Find out reasons why items got unpublished and republish them. Find out what is the total cost of all items unpublished for a specific reason

• Get Unpublished Item Count API – Specify a date to return all unpublished items since that date. Response includes total count of unique items unpublished per reason code, with total cost of all unpublished items per reason code.
• Get Unpublished Items API – Specify reason code, to return item details.

To fine-tune your offerings, and republish items that went unpublished, you can use Unpublished Items API.

Listing Quality API

Sellers can optimize and grow their business by learning key metrics about the quality of their listings, and get their overall listing quality score with the Listing Quality API.

• Get seller’s listing quality score – View a seller’s Listing Quality score for their entire catalog of listings with the Seller Listing Quality Score API.
• Find categories with Listing Quality issues –  locate all item categories that currently have items with Listing Quality issues, use GET Categories with Listing Quality Issues API.
• Filter for item listing quality metrics – look at item-level listing quality details with the Item Listing Quality Details API.

About Listing Quality

Item listing quality is based on four metric categories. These metrics measure the overall and item-level listing quality for sellers:

• Content – Item title (i.e. inaccurate product name), item description (e.g. missing, misspelled, too long) and image quality (e.g. not enough images, low resolution).
• Discoverability – how easy it is for buyers to locate your items by how they populate the left navigation and in searches. This includes attributes for brand, manufacturer part numbers, colors, and size.
• Offer – how competitive the price is compared to other sellers, how many shipping speeds are provided (e.g. (TwoDay, ThreeDay), whether or not the item is published and available for sale (i.e. inventory is available).
• Ratings & Reviews – buyer rating and reviews for your items.

To see a comprehensive list of Listing Quality issues, see Content and Discoverability section in the Seller Help article.

To view your seller’s Listing Quality score in the Seller Center, go to the Listing Quality Dashboard under Analytics > Growth Opportunities.

You can grow your business by adding the top trending item best sellers at Walmart to your seller catalog with the Trending Items API. Best selling items are ranked and you can search for best sellers within each item department or department category.

The Trending Items API returns all items with rank values 1 through 5. A rank of 5 or above indicates a best seller.

Step 1: Get the department names and IDs

First, you need to select the department or department category of item top sellers.

Call GET All Departments API to return a list of all department names and department IDs. For example, call: /v3/utilities/taxonomy/departments

This call returns all department names and department IDs in JSON format.

Example: Get all departments

{
     "superDepartment": "PETS AND SUPPLIES",
     "superDepartmentId": "47000",
     "departments": [
         {
            "departmentName": "LARGE PET DURABLES",
            "departmentId": "47010"
          },
          {
            "departmentName": "CAT FOOD",
            "departmentId": "47011"
           },
           {
            "departmentName": "SMALL PET DURABLES",
            "departmentId": "47015"
            },
            {
              "departmentName": "DOG FOOD",
              "departmentId": "47002"
            }
            ]
}

Now that you have the department ID, you can provide it to get the top sellers in that department.

(Optional) Step 2: Get the categories and IDs

Similarly, to get category names and IDs within a department, call GET All Categories API and specify the departmentId.

For example: /v3/utilities/taxonomy/departments/1021082

This returns the department name & department ID, with list of all category names and categoryId for that department. For example, here are the categories within the Audio department.

Example: All category names in Audio department

{
    "status": "SUCCESS",
    "payload": {
        "departmentName": "AUDIO",
        "departmentId": "1021082",
        "categories": [
            {
                "categoryName": "HEADPHONES L3",
                "categoryId": "1021180"
            },
            {
                "categoryName": "HOME THEATER L3",
                "categoryId": "1021183"
            },
            {
                "categoryName": "AUDIO HARDWARE",
                "categoryId": "1021172"
            },
            {
                "categoryName": "MP3 PLAYERS L3",
                "categoryId": "1021181"
            },
            {
                "categoryName": "SPEAKERS L3",
                "categoryId": "1021182"
            }
        ]
    }

Step 3: Get the top selling items for that department

Now that you have the department ID that you want, you can search for top trending items within that department.
You must provide the departmentId, and optionally you can make your search specific to a category by adding categoryId as an optional request parameter.

To get the best sellers in the Audio department, call:

/v3/insights/items/trending?departmentId=1021082

Upon success, this API call returns the list of top ranked items from 1 to 20.

For example, you can see the top three best sellers for Audio department, and gain valuable insights, such as rank for each item, and if this item exists for you. It also provides item details that will easily allow you to ingest and publish the item, such as itemId, and 2day eligible.

Example: Top 3 best sellers in Audio

{
                "departmentName": "AUDIO",
                "categoryName": "HEADPHONES L3",
                "productName": "Apple AirPods Pro",
                "subCategoryName": "WIRELESS HEADPHONES",
                "isTwoDayEligible": 1,
                "itemId": "520468661",
                "totalOffers": 9,
                "superDepartmentName": "72 ELECTRONICS",
                "existsForSeller": 0,
                "rank": 1,
                "brand": "Apple"
            },
            {
                "departmentName": "AUDIO",
                "categoryName": "SPEAKERS L3",
                "productName": "JBL Flip Essential Bluetooth Speaker",
                "subCategoryName": "WIRELESS SPEAKERS",
                "isTwoDayEligible": 0,
                "itemId": "368861200",
                "totalOffers": 0,
                "superDepartmentName": "72 ELECTRONICS",
                "existsForSeller": 0,
                "rank": 2,
                "brand": "JBL"
            },
            {
                "departmentName": "AUDIO",
                "categoryName": "HEADPHONES L3",
                "productName": "onn. True Wireless Earphones, White",
                "subCategoryName": "IN EAR HEADPHONES",
                "isTwoDayEligible": 1,
                "itemId": "283162082",
                "totalOffers": 1,
                "superDepartmentName": "72 ELECTRONICS",
                "existsForSeller": 0,
                "rank": 3,
                "brand": "onn."
            }
 

Step 4: Get top selling items within a department category

To get top trending items within the Audio department, specifically headphones category, call:

/v3/insights/items/trending?departmentId=1021082&categoryId=1021180

Upon success, it returns the top ranked best-selling items in the Headphones category.

For example, here are the top two best sellers for Headphones: Airpods Pro is number 1 best seller, and onn Wireless earphones is number 3 best seller.

Example: Top trending items by department category

{
                "departmentName": "AUDIO",
                "categoryName": "HEADPHONES L3",
                "productName": "Apple AirPods Pro",
                "subCategoryName": "WIRELESS HEADPHONES",
                "isTwoDayEligible": 1,
                "itemId": "520468661",
                "totalOffers": 9,
                "superDepartmentName": "72 ELECTRONICS",
                "existsForSeller": 0,
                "rank": 1,
                "brand": "Apple"
            },
            {
                "departmentName": "AUDIO",
                "isbn": "",
                "categoryName": "HEADPHONES L3",
                "productName": "onn. True Wireless Earphones, White",
                "subCategoryName": "IN EAR HEADPHONES",
                "isTwoDayEligible": 1,
                "itemId": "283162082",
                "totalOffers": 1,
                "superDepartmentName": "72 ELECTRONICS",
                "existsForSeller": 0,
                "rank": 3,
            },

Marketplace sellers can use the Unpublished Item Count and Unpublished Items APIs to figure out why items get unpublished, and how many items are unpublished for each reason. 

There are many reasons why items get unpublished, either by Walmart actions, or by a seller’s action. Some reasons include: Item’s end date has passed, so it goes unpublished. Or, If the item image is missing, it can trigger item to get unpublished. These simple fixes can get your items republished so you can win more sales and grow your business.

The top 5 reasons items go unpublished are:

• End Date Issue
• Reasonable Price Not Satisfied
• No Primary Image
• Start Date Issue
• No Price

To find out why an item was unpublished, use the Unpublished Items API to locate the reason code. To get a complete list of reason codes, see Unpublished Item Reason Codes.

Unpublished items workflow

1. Use Unpublished Item Count API to get a list of all unpublished item reason codes after a specific date. The response includes a list of all groups of unpublished item information, grouped by:
   • Count of unique item SKUs unpublished by specific reason code
   • Unpublished item reason code
   • Total cost for all items unpublished for that reason
2. Use Unpublished Items API to return all item details with the reason code you pass in.
3. Re-ingest and publish your item again. See Item Management API Overview.

Note: All API call examples shown in this tutorial assume the API endpoint is prepended to the call.

Walmart API endpoint: https://marketplace.walmartapis.com

Step 1: Get a list of all unpublished items with reason codes

To get a list of all reasons why items were unpublished since a certain date, Call GET Unpublished Item Counts API and specify the fromDate parameter. 

Consider this example: to return a list of how many items were unpublished for each possible reason after April 1, 2020, call:

/v3/insights/items/unpublished/counts?fromDate=2020-04-01

Upon success, the API returns the total number of distinct items SKUs that were unpublished by a specific reason code, and the total cost of the unpublished items.

Here is example response that includes reason code: END_DATE, number of items unpublished for that reason, and total cost of the unpublished items:

"unpublishedCount": "185",
"unpublishedValue": "2154.0",
"unpublishedReasonCode": "END_DATE"

In the list of reason codes provided, there are 185 unique item SKUs with expired end dates that were unpublished.

Now that you have the reason code END_DATE, you can make a call to GET Unpublished Items API to return all item-level details for item SKUs unpublished for that reason.

Step 2: Get item details for unpublished items

Now you can pass in the reason code to GET Unpublished Items API. It will return all the item-level information for each item that was unpublished with that reason code.

For example, to get all items unpublished for END_DATE reason code after Sept. 14, 2020, call:

/v3/insights/items/unpublished/items?fromDate=2020-09-14&unpublishedReasonCode=END_DATE

All item-level information is returned for any unpublished items with the reason code you specify, such as:

• Item SKU, ID, and product name
• Item is trending or not
• Item lifecycle status
• Item publish status

For the complete list of response parameters, and sample response JSON payloads, see Unpublished Items API Reference.

(Optional): Get list of all unpublished items for all reasons

You can also get a full list of all unpublished items for all reason codes.

Call GET Unpublished Items API and specify fromDate parameter only. By default, if you do not provide a reason code, it returns all reason codes.

For example to get a list of all unpublished items since Jan. 15th, 2020 call:

/v3/insights/items/unpublished/items?fromDate=2020-01-15

Step 3: Re-publish Items with Item APIs

Now you can republish the items using item information provided by Insights APIs: Unpublished Item Counts and Unpublished Items APIs. See Set up and publish items.

Unpublished Item Reason Codes

These are all unpublished item reason codes available.

Unpublished Reason Code	Description
START_DATE	Your item’s start date occurs in the future. Your item will be published after the start date arrives.
END_DATE	Your item is unpublished because the end date has passed. To republish your item, re-ingest the item with a new start and end date.
REASONABLE_PRICE_NOT_SATISFIED	Customers would save drastically by purchasing this item on a competing website. When unpublished item prices are back within an acceptable range, Walmart will automatically republish the item.
PRIMARY_IMAGE_MISSING	There is no primary image for your item. After you re-ingest this item with a valid primary image, your item will be republished.
NO_PRICE	No price was found for this listing.

You can view your seller’s Listing Quality score for your entire catalog of listings with the Seller Listing Quality Score API.

The Listing Quality score is based on several metrics that gauge the quality of your item listings: Content, Discoverability, Offer, Ratings and Reviews. If there are issues in these metric categories, your seller’s overall score will decrease.

To view your seller’s Listing Quality score in the Seller Center, go to the Listing Quality Dashboard under Analytics > Growth Opportunities.

Step 1: Call Seller Listing Quality Score API

To get a seller’s overall Listing Quality Score, call:

/v3/insights/items/listingQuality/score

Note: All API call examples shown in this guide assume the Walmart API endpoint: https://marketplace.walmartapis.com

The API returns the following listing quality metrics for the seller’s overall catalog:

• Overall Listing Quality – overAllQuality provides the seller’s overall score with range of values from 0 to 100. Score includes seller’s trending items, and WFS items (if seller participates with Walmart Fulfillment Services) by default. You can exclude these from the score with the query parameters.
• Offer – offerScore value 0 to 100 (e.g. “offerScore”: 56.38)
• Content – contentScore value 0 to 100 (e.g. “contentScore”: 78.0)
• Ratings & Reviews – ratingReviewScore value 0 to 100 (e.g.    “ratingReviewScore”: 100.0)
• Post-purchase Quality – itemDefectCnt provides the number of items with issues. defectRatio provides a ratio of available items to defective items.

Upon success, the API returns all metrics with status “OK.”

NOTE: To see a response sample, see Response Samples in the Seller Listing Quality Score API Reference.

Step 2: (Optional) Exclude trending items in LQ score

If you want to exclude the seller’s items that are trending (e.g. “in demand” items by rank) in the overall Listing Quality score, you can use the viewTrendingItems query parameter set to “false.”

For example, to opt-out of including trending items in the LQ score:

/v3/insights/items/listingQuality/score?viewTrendingItems=false

Step 3: (Optional) Exclude WFS-eligible items from LQ score

If you want the seller’s Listing Quality score to exclude the WFS-eligible items, use the query parameter wfsFlag set to “false.”

Note: This only pertains to sellers that participate in Walmart Fulfillment Services and have published their items for distribution with WFS.

For example, to opt-out of including WFS items in the Listing Quality score:

/v3/insights/items/listingQuality/score?wfsFlag=false

To locate all item categories that currently have items with Listing Quality issues, use GET Categories with Listing Quality Issues API.

As a seller, you can use this API to identify which items have problems with your listings so that you can fix the issues and increase sales with better quality listings.

Step 1: Call GET Categories with Listing Quality Issues API

Call the API /v3/insights/items/listingQuality/count

You can find the number of items within each category that has Listing Quality issues.

Step 2: (Optional) Request trending items or WFS items

You can specify query parameters to include or not include items that are top trending items, WFS-eligible items (for sellers that participate with Walmart Fulfillment Services), or items that have listing quality issues.

To get these listing quality details, use the viewTrendingItems, wfsFlag query parameters set to “true” and hasIssue set to “1”. Similarly, to exclude these items from the categories returned with issues, set the hasIssue query parameter to “0”.

For example, to include top trending items, call:

/v3/insights/items/listingQuality/categories?viewTrendingItems=true

Note: The wfsFlag parameter only pertains to sellers that participate in Walmart Fulfillment Services and have published their items for distribution with WFS.

You can also look up items that are top-trending items, Walmart Best Sellers, see Assortment Growth in the Seller Center.

Step 3: View the response content

After you call the Categories with Listing Quality Issues API, the response returns the following information:

• category – Specifies the main category name.
• offerCount – Specifies the number of items with issues within this category.
• productType – Specifies a sub-category of product within the main category.
• productTypeName– Specifies the product name within the product type.

For example, if you have issues with your items in the Furniture category, a response would return the total number of items with issues specified by offerCount (e.g. 47,000). It also provides issue counts for product types within that category (e.g. Table).

   "category": "Furniture",
   "offerCount": 47000,
   "productType": [
       {
          "productTypeName": "Table",
          "offerCount": 20000
        }

To learn more about Listing Quality issues, see the Seller Help article.

To get a list of hints to help you fix these content issues with your item listings, see Content and Discoverability section in the Seller Help article.

You can look at item-level listing quality details with the Item Listing Quality Details API. Refer to the API throttling guide here to understand the usage limitations for this API.

To view a detailed description for all Listing Quality metrics, see Content and Discoverability section in the Seller Help article.

To view your seller’s Listing Quality score in the Seller Center, go to the Listing Quality Dashboard under Analytics > Growth Opportunities.

There are two ways to filter for an item’s specific listing quality metric that you want:

Filter fields – You can use filters with operators to specify category/product type or select a range of values to return.

Query fields – You can use the query parameter to specify either of three fields: SKU, Title or Item ID.

Option 1: Use filter field with operators

You can use filters in the request body to return specific metrics that you want to see for your items.

You can request an item’s score returned as percent value for these metrics using filters: content discoverability, quality, offer, ratings & reviews. You can also filter for items that: have issues, are a specific product type, are within a category, or that are WFS-eligible.

Filter Operators

You need to specify the attribute to filter the responses returned, and an operator (either “equals” or “between”).

Operator	Description and acceptable value	Usage
equals	Returns an exact match for any specified String.	“op”: “equals”, “values”: [“Music”]
between	Returns any items within the range of two integer values specified.	“op”: “between”, “values”: [ 10, 50 ]

Note: To see the complete list of filters available, with descriptions, see filters in the Request Body Schema section of the Item Listing Quality Details API Reference.

Filter Example: ProductType and Post-purchase Issues

To filter item details by Product Type and return all items with post-purchase issues, you can use the filters: viewPostPurchaseItems and productType.

This request will return all the items with post purchase issues for a specific product type:

{
  "filters": [
    {
      "field": "viewPostPurchaseItems",
      "op": "equals",

      "values": [0]
    },
    {
      "field": "productType",
      "op": "equals",
      "values": ["Music"]
    }
  ]

NOTE: To see a response sample, see Response Samples in the Item Listing Quality Details API Reference.

Option 2: Use query parameter with fields: SKU, title and item id

You can limit your search for item-level listing quality details either by: Item Title, SKU, or Item ID with query fields: sku, title, or itemId.

To specify the query parameter, you need to include the field and value in the body of the request.

Example Request Body: filter for item ID

For example, to query by item ID, specify field name itemId and Value(s) in the request body:

   "query": {
     "field": "itemId",
     "value": "916854860"
   } 

Similarly, you can specify the sku or title fields, and provide the value.

You can also search multiple items, skus with Comma-separated Value(s)

Example Request body: filter for multiple item ID

For example, to query by multiple item ID, specify the field name itemId and Value(s) in the request body:

"query": {
"field": ïtemId",
"value": "916854860,916854862,916854862,916854863"
}

NOTE: 1. Multiple value is supportd for item id or sku id only with max supported limit as 200. 2. To see a response sample, see Response Samples in the Item Listing Quality Details API Reference.

Limit number of item details to return

To limit the number of items that return listing quality details, you can specify limit query parameter to only return a specific number of items in the response. By default, if no limit is specified, the API returns 200 items per page.

Use nextCursor to return next set of 200 items

Use the nextCursor query parameter to indicate pagination between each 200 items returned (the default limit). An initial API call response contains a nextCursor value.

Example: nextCursor returned in initial response

"nextCursor": "AoIFQCVXCj1wo9c/ATA3MTY0MyMTE4QTc2RTA5",

Specify this value in a subsequent request to return the next 200 items:

/v3/insights/item/listingQuality/items?nextCursor=ATA3MTY0MyMTE4QTc2RTA5

To get items 201-400, make a subsequent API call and specify nextCursor value to start the list to be returned.

Recommendations

• • To fetch all items in your catalog, use cursor along with query parameter with limit 200.
• • Item can be categorized by category or product type. To access this mention category name or product type along with limit 200 to get as many items.
• • Avoid accessing API’s one at time with itemId, sku or title fields to get multiple items, rather use category, product type with a limit of 200 to get multiple items specific to the category, product type.

You can view your seller’s badge status with the Pro Seller Badge API. The Pro Seller Badge is a badge that is given to Sellers to demonstrate that they are providing great service and have a high-quality catalog. The badge refreshes every 5th and 20th of each month (Walmart reserves the right to modify this at any time). To view your Seller’s badge status in Seller Center, go to the Listing Quality & Rewards Dashboard under Analytics → Growth Opportunities. For more information on the criteria and the Pro Seller Program, please visit our program page here.