Items

You can set up your items for sale on Walmart.com with the Item Management API. Walmart classifies a product with its corresponding listing price information as an “item.” To make your items available for customers to purchase on Walmart.com the items must have their prices adjusted (optional), have inventory assigned, submitted and published.

Note: You need to complete seller registration, and get your API Key (Client Secret and Client ID) to start item integration. To access your API Key, go to My Account. Select Login Type, choose Marketplace to get to API Keys.

Submit and publish processes

As a seller, you trigger the submit and publish processes in a single action. To add or change inventory requires a separate action.

Item submit process will parse and classify an item. This process typically takes a few hours. Item publish process requires Walmart systems to process items that have all necessary attributes confirmed. This typically takes a few hours.

Note: We recommend that you set up a process to monitor and ensure that your items get pushed to Walmart.com.

Setup Item Variants with APIs

The Get item count by groups API allows you quickly view the item variant group IDs and counts of variant groups. With the data from this API, you can use it to filter Get All Items API, Get and item API, and Catalog Search API.

• – Catalog Search: Add the additional query below to search for the variant Group ID with the Catalog Search API.

"query": {
    "field": "variantGroupId",
    "value": "string"
}

To learn about how to group items, see Variant Setup.

About item spec versions

The Marketplace APIs provides one item spec version: item spec v4.X. The legacy version v3.2 does not provide the enhanced setup workflow, and will be deprecated on October 1, 2022 . We recommend that you use the new optimized Item spec v4.X and new feed types when you do your initial setup with the Bulk item setup API. To learn more about item setup strategies and concepts, see SellerHelp Walmart. To learn how to set up items in bulk, see Add Items in Bulk.

Optimized Item setup and maintenance with Item Spec v4.X

Item spec v4.x optimizes the Walmart Global Data Model with new and improved existing attributes, and a faster, more efficient item setup and maintenance process. Improvements include:

• – Better data definitions, modern attribute names, and precise attribute organization.
• – Increased buyer search discoverability for your items.
• – Increased variant grouping options that organize products in site navigation for better buyer visibility.
• – New product and compliance attributes.
• – Single setup process with one spec for combined Marketplace and WFS items.
• – Automated product tax code assignment.
• – Ability to set Sales restrictions for WFS-eligible items by state or zip code due to reasons: Commercial, or Illegal for sale.

The new Item spec v4.X provides three sets of JSON schemas that you can use with the new feed types to represent an item object for either Marketplace item, Marketplace, WFS item, or Item maintenance. Select the JSON schema depending on whether you are creating new items for Walmart alone, Walmart, and WFS, or you are maintaining items that are currently set up. Spec v4.X is available in JSON schema format only for better ease of use.

Changes in Spec v4.6

• Adding Sales Restrictions in 8 additional categories:

1. Animal Other
2. Beauty, Personal Care & Hygiene
3. Garden & Patio
4. Home Decor, Kitchen & Other
5. Land Vehicles
6. Sports & Recreation Other
7. Vehicle Other
8. Vehicle Parts & Accessories

If a seller is setting up items in these 8 categories, they are required to complete Restriction Type.
– Additional Details: If the seller selects Restriction Type (Commercial, Illegal for Sale), they are also required to complete one of the below attributes:
– States: List all States where your product should not be sold for legal or commercial reasons
– Zip Code: List all zip codes where your product should not be sold for legal or commercial reasons

-Adding “Fit Type” as an optional attribute to ‘Vehicle Other’ category
-Adding “Is Smart” as an optional attribute to ‘Furniture’ and ‘Home Decor, Kitchen & Other’ categories

Item Specs v4.X

• `To create new items for Walmart only: MP_ITEM_SPEC_4.6.json
  Use feedType=MP_ITEM
• To create new items for Walmart and WFS: MP_WFS_ITEM_SPEC_4.3.json
  Use feedType=MP_WFS_ITEM
• To change or update an existing item for Walmart and WFS: MP_MAINTENANCE_SPEC_4.6.json
  Use feedType=MP_MAINTENANCE

WFS conversion Spec

To convert an existing item to WFS, download the WFS Item conversion JSON schema: WFS_Convert_Schema_v4.5.json
Use feedType=OMNI_WFS

For detailed instructions to convert items for WFS, see Make items eligible for WFS fulfillment.

Starting October 1, 2022 our systems will no longer support item setup or maintenance using legacy Item Spec v3.2. Marketplace sellers should start migrating to the latest 4.X versions now in order to avoid delays to your item setup and maintenance requests.

In order to streamline your migration effort the document below is a comprehensive breakdown of attribute value changes form 3.2 to 4.X. Please utilize this template to simplify your migration efforts.
Review the comparison for migrating from Item Spec v3.2 to Item Spec v4.X.

To initially set up and ingest your items to Walmart, you need to use several different APIs.

There are two ways you can set up seller items:

• Ingest new items into Walmart databases and publish them catalog. See Set up item: ingest new items
• Match your items to existing items in the Walmart.com catalog. See Set up items : match Walmart items

Prerequisite: Download Item spec

To select the Item spec for your purposes, see Item Spec v4.X.

Item setup steps

 

1. Send an item feed to Walmart with payload in JSON format. Go to Items > Bulk item setup to make the initial API request that starts the ingestion and publish process for each item you send in the API call. The response returns a Feed ID that you can use to monitor all items you want to ingest.
   Note: In an Item feed, if you send HTML content as a value to shortDescription you have to do character encoding to the HTML tags. If you send direct HTML tags, they will appear as is in the Description of an Item on Walmart.com.
2. Monitor the feed and the item submission status. Go to Feeds > Get feed and item status to retrieve all details about the Feed status. Once the Feed has a status of PROCESSED (i.e. the Feed is complete), all of the items have either been submitted or have submission errors.Note: The first items may be successfully submitted days before the last items get submitted.
3. Monitor the published status of the submitted items. Go to Item > Get an item to check the status. Once the status of an item is PUBLISHED, it can be edited further.Note: Status calls might return errors on individual items. Examine the errors that are returned, correct them and then mark them for re-ingestion.
4. (Recommended): To change the price of your items, go to Price > Update a price. You can update prices in bulk, go to Price > Update a price. Although this is not required, it’s a good practice to verify prices, because desired item prices can change after you initiate the ingestion process.
5. Update inventory for one or more items. Go to Inventory > Update inventory or Inventory > Bulk update.

To initially ingest and publish new items to the Walmart catalog, use the Bulk Item Setup API to update items in bulk.

Typically, sellers can update 10,000 items at once. However, the 10K item limit does vary depending on individual seller agreements, it might be only 5K for some sellers.

Provide Sales Restriction Type

There is a requirement for setting up WFS items and Walmart items in Furniture and Large Appliance categories to indicate item Sales Restrictions by geographic location: State or Zip Code. If there are no restrictions, you can set the Restriction Type to “None.” Sellers must select an option for a restriction (Commercial, Illegal for Sale, or None), you must complete the following attributes if you choose the first two options:

• States: List all States where your product should not be sold for legal or commercial reasons separated by a comma. (E.g., CA, IL, IA, MN, NY, UT, TX)
• Zip Code: List all Zip Codes where your product should not be sold for legal or commercial reasons separated by a comma. (E.g., 86401, 50432, 99543, 23451, 88231)

To set up items that match existing items in Walmart.com, call POST /v3/feeds with feedType set to MP_ITEM_MATCH.

For example:

https://marketplace.walmartapis.com/v3/feeds?feedType=MP_ITEM_MATCH

Use the Item Setup by Match schema and update the information as per the Setup by Match v4 schema for each item. The items you submit will be processed and checked to see if they already exist in the Walmart Catalog. If a match is found, your item will be automatically set up and you won’t need to provide your own content.

Once the feed has been processed, the Feed Item Status API will return whether a match is found or not. If a match is not found or you want to provide your own content, use the Bulk Item Setup API.

Item Setup by Match JSON schema

Download the Item Setup by Match API JSON schema:

MP_ITEM_MATCHv4.json

The MPitem object may contain either item or listing/offer information, or both. Based on the type of information it can be used for the following operations:

1. To Set Up Full Item: If the MPitem object contains item information (i.e., item attributes) as well as the listing /offer information (i.e., price and shipping information); it will be used to set up the full item.
2. To Update Product Only: If the MPitem object contains only item information (i.e., item attributes); it will be used for only product information updates.
3. To Update Listing/Offer Only: If the MPitem object contains only listing /offer information; it will be used for only listing/offer information updates.

Which object to use for initial set up, publish and edit operations

Select either the Item, Offer Only, or Product Only object for the stage in setup or maintenance that you are doing:

1. For initial insertion, use the MPItem object with item details and item listing or offer.
2. Once the item has been set up and the status is PUBLISHED, use the Offer Only object item for non-item edits, such as price changes.
3. Use the Product only item object for item edits. You should not use an MPItem object because any price change included in the MPItem object is effective only when the entire object is processed.

Lifecycle Status

The lifecycle status of an item describes where the item listing is in the overall lifecycle.

1. ACTIVE: The item’s offer is current.
2. RETIRED: The offer has moved past its expiration date (as set in the EndDate field). The item is not visible on Walmart.com. It can be made ACTIVE again by extending the expiration date into the future.
3. ARCHIVED: The offer has been in RETIRED status for over a year. To return the listing to the ACTIVE status, contact Partner Support.

To maintain an item, keep track of process modes, product ID & SKU, and shipping override.

Process Mode & Subset

For MP v4.X, you should always pass REPLACE for process mode and EXTERNAL for subset.

Product ID & SKU

Product ID and SKU are important identifiers for Walmart’s systems. Walmart merges items with the same Product ID and shows them as one item sold by multiple Sellers. If you provide the wrong Product ID, your item will be merged incorrectly, which can increase your order cancellation rate, create bad customer experience, produce customer fraud complaints and result in a lower rating on your Seller Scorecard.

**Note: You can not update both a SKU and a product ID in the same spec. If you want to update the product ID, it must be done separately. For more details, please refer to Update an Item’s Product ID.

Secondary Image Deletion

To delete old SECONDARY/SWATCH images, please send the value for processMode as REPLACE_ALL.

The Walmart Item Search API allows you to query the Walmart.com global product catalog by item keyword, UPC or GTIN. You can review all item information provided in the response, so you can decide whether or not you want to sell this item.

You must specify at least one query parameter, either: query, gtin, or upc. If there are more than one item in the catalog, the search returns the first 20 items in the response. Additionally, you can use the information provided in the ​relatedQueries ​response parameter to run a new search for similar items.

Search by keyword, UPC or GTIN

To search for a product in the Walmart global catalog, call GET /v3/items/walmart/search, and specify query parameters: query for a keyword search, upc for Universal Product Code search, or gtin to get the Global Trade Item Number.

Example: Search by keyword

For example, to search for a keyword, enter text (e.g. ipad or fitbit) with the query parameter:

GET https://marketplace.walmartapis.com/v3/items/walmart/search?query=ipad

Example: Search by UPC

To search by UPC code, specify the number with the upc parameter:

GET https://marketplace.walmartapis.com/v3/items/walmart/search?upc=​911138034047

Upon success, the response returns all values for the item in JSON format.

The seller item search API allows you to search a seller’s catalog by seller’s Item_ID, GTIN, UPC, EAN, ISBN, or SKU.

To search for a seller’s item by specific product code, call GET v3/items resource, and specify the productIdType query parameter set to ITEM_ID, GTIN, UPC, ISBN, EAN, or SKU.

You must specify at least one value for the productIdType query parameter (e.g. productIdType=GTIN), or else the API returns SKU by default.

If there are more than one item in the catalog, the search returns the first 20 items in the response. Additionally, you can use the information provided in the ​relatedQueries ​response parameter to run a new search for similar items.

Get an item by SKU

You can pass the SKU code directly as the URL parameter, ID:

https://marketplace.walmartapis.com/v3/items/{ID}

For example, to get the SKU code, “30348_KFTest,” specify it directly to the items resource as a URL parameter:

 https://marketplace.walmartapis.com/v3/items/30348_KFTest

Get an item by specific codes

To get other item codes, specify the query parameter productIdType set to either GTIN, UPC, EAN, ISBN, SKU or ITEM_ID and provide the numeric code after the /items resource in the URL.

Example: get an item by GTIN

https://marketplace.walmartapis.com/v3/items/06932096330348?productIdType=GTIN

Example: get an item by UPC

https://marketplace.walmartapis.com/v3/items/123456789012?productIdType=UPC

Example: get an item by EAN

https://marketplace.walmartapis.com/v3/items/5901234123457?productIdType=EAN

Example: get an item by ISBN

https://marketplace.walmartapis.com/v3/items/1514735164?productIdType=ISBN

Example: get an item by ITEM_ID

https://marketplace.walmartapis.com/v3/items/0935829?productIdType=ITEM_ID

Example: get an item by SKU

https://marketplace.walmartapis.com/v3/items/30348_KFTest?productIdType=SKU

Upon success, the response returns all values for the item in JSON format.

The Catalog Search Api allows you to make a more accurate request to  search Seller Catalog by creating your own payload and not in the url.

To make the search, call /v3/items/catalog/search resource, and specify the correct payload with Query, Filter and Sort. Please see allowed fields for those parts below.

You must provide either Query or Filter to execute search API call. Sort along is not sufficient as a standalone parameter for API call and will lead to an error response. 

Only one query is allowed but multiple filters are acceptable.

White card search is supported for Query, use “%” to present the unknown letters. For example, “%item” means any string ended with “item”, “item%” means any string started with “item” and “%item%” means any string contains “item”.

Allowed fields for Query:

“productName” “sku” “gtin” “wpid” “upc” “isbn” “ean” “itemId”

Allowed fields for Filters:

“num_reviews” “customerRating” “lifecycleStatus” “publishedStatus” “unpublishedReasons” “inventoryStatus” “price” “fulfillmentType”

Allowed fields for Sort:

“num_reviews” “customerRating” “lifecycleStatus” “publishedStatus” “unpublishedReasons” “inventoryStatus”

Limit and pagination 

you can simply attached the limit and pagination/nextCursor at the end of url

/v3/items/catalog/search?limit={limit}&nextCursor={nextCursor}

for example if i select limit as 10 and applied nextCursor, it will be like this:

/v3/items/catalog/search?limit=10&nextCursor=DnF1ZXJ5VGhlbkZldGNoeAAAAAAC4JCoFjQ(omit the rest)

Please do not apply nextCursor when you do the search for the first time.

Examples: Only search with Query

White card search is supported for query. Like below example, % is used to indicate “Unknown”. So in this case, it will search any sku contains letter “n”.

{
   "query": {
     "field": "sku",
     "value": "%n%"
   }
 }

Examples: Only search with Filters

Multi-field is supported in filters, you can combine any filters you like to search. So in this case, we are doing search for all the items which match two judgement, price is larger than 10 and unpublishedStatus is either PUBLISHED or RETIRED.

{
   "filters": [
     {
       "field": "price",
       "op": "larger_than",
       "values": [
         10
       ]
     },
     {
       "field": "unpublishedStatus",
       "op": "equals",
       "values": [
         "PUBLISHED",
         "RETIRED"
       ]
     }
   ]
 }

Examples: Sort- now allowed to show in payload alone.

Sort is not allowed to show in payload alone, you must have either query or filters before Sort. And it support either ASC or DESC. 

{
   "sort": {
     "field": "unpublishedStatus",
     "order": "ASC"
   }
 }

Examples: Search with combination of Query, Filters and Sort

{
   "query": {
     "field": "sku",
     "value": "%n%"
   },
   "filters": [
     {
       "field": "price",
       "op": "larger_than",
       "values": [
         10
       ]
     },
     {
       "field": "unpublishedStatus",
       "op": "equals",
       "values": [
         "PUBLISHED",
         "RETIRED"
       ]
     }
   ],
   "sort": {
     "field": "unpublishedStatus",
     "order": "ASC"
   }
 }

After you create the Shipping Template, you can associate items that use it by mapping the product SKU to the template.

To learn how to create a shipping template, see Create Shipping Template in Settings guide.

Step 1: Map the SKU to a shipping template

To map an item SKU to a shipping template, use the Bulk Item Setup (Multiple) API. Specify SKU_TEMPLATE_MAP for the feed type. For example, call POST /v3/feeds?feedType=SKU_TEMPLATE_MAP

Provide your sample file with values for required parameters in your request payload:

• sku – Item SKU code
• actionType – Specify “Add” to associate SKU to the template
• shippingTemplateId – provide the Shipping Template ID that you want to associate the SKU to
• fulfillmentCenterId – provide the Fulfillment Center ID

To view an example, see Bulk Item Setup (Multiple) API Reference. Go to the Request Samples pane, and select “SKU_TEMPLATE_MAP – Sample 1” from the Example drop-down menu.

Note: Make sure to send the feed file as an attachment set the Content type to “multipart/form-data” in the header.

Step 2: Specify Shipping Overrides

To set up your shipping overrides, use Bulk Item Setup (Multiple) API.

For example, call POST /v3/feeds?feedType=SHIPPING_OVERRIDE

You need to provide values for Override and ShippingOverride

Specify all of the request parameters depending on the settings you want for this shipping template.

1. Create the rule to override current settings for this SKU. SKU, Fulfillment Center ID, and action type (e.g. UPDATE).
   • Item SKU
   • actionType – e.g. “actionType”: “UPDATE”
   • Fulfillment Center – e.g. “fulfilmentCenterId”: “83746529874858430”
2. Specify all parameters for ShippingOverride. Provide details about shipping method, and regions from which this fulfillment center should distribute.
   • shipMethod – e.g. “EXPEDITED”
   • actionType – “REPLACE”
   • States in each region for this FC to service: (e.g. “northeastRegionStates”: “CT,NJ,NY”).

To view an example, see Bulk Item Setup (Multiple) API Reference. Go to the Request sample pane, and select “SHIPPING_OVERRIDES – Sample 1.”

In this example, a sku is updated to provide expedited shipping to specific states per region.

For more details about shipping overrides, see Shipping Overrides.

To learn more about shipping overrides, and use case examples, see Seller Help Knowledge Base.

(Optional) Step 3: Set up a Shipping Rule

If you prefer to opt-out of the precise delivery available with Shipping Templates, you can simply set up a TwoDay shipping rule with Create a new Rule API.
To learn more about the Rules API, see Rules Management.

If you have already onboarded to the TwoDay program, before you activated the Shipping Templates, you can switch back to TwoDay shipping. For a mapping of activation status and program onboarding status, see Rules Management.

Validation Error Troubleshooting

When you send a SKU_TEMPLATE_MAP feed to Walmart, it validates according to Attribute type and acceptable format.

If you provide an incorrect Shipping Template ID, Fulfillment Center ID, or invalid SKU, you will get data or system errors. Here are some tips to fix the errors.

Error Type	Cause	How to fix or avoid error
DATA_ERROR	Shipping Template ID is invalid	Verify the Shipping Template ID and resend request.
DATA_ERROR	Fulfillment center ID is invalid.	Provide correct FC ID and resend request.
DATA_ERROR	SKU is missing from the request. Or, SKU is invalid.	Provide SKU and resend the request. Verify SKU format is correct, and retry request.
SYSTEM_ERROR	SKU provided in request is not found in the system.	Make sure that the correct item SKU was ingested in the system. To ingest the item again, call Bulk Item Setup API. Please provide a valid SKU in the payload line items and reattempt. If the issue persists, contact the support team at https://sellerhelp.walmart.com/s/.

Get Feed Status Errors

If you call Get Feed Status API it might fail if you do not include all required parameters in the request.

Make sure that you include the selling channel in the request.

For example:

  "ItemFeedHeader": {
    "sellingChannel": "precisedelivery",
    "locale": "en",
    "version": "1.0"

For a sample request for the SKU template map feed, see https://developer.walmart.com/api/us/mp/items#operation/itemBulkUploadsSelect SKU_TEMPLATE_MAP from the Sample pane drop-down menu to view the full sample.

As part of Precise Delivery Program, Sellers and Channel Partners can associate SKUs to Shipping Template(s). The initial configuration is set with the Bulk Item Setup (Multiple) API.

Previously, sellers could only check which Shipping Templates are associated with item SKUs by downloading an item report.

Now you can get all Shipping Templates and Fulfillment Centers that are currently associated with each item SKU. Call the POST Get Item Associations API to view current item SKU Shipping Template associations that you’ve set up with the Bulk Item Setup API. For information about how to set this up, see Add an item SKU to a Shipping Template.

Note: The Item map to Shipping Template process takes between 30 minutes to 4 hours. After this, you can call POST Get Item Associations API to retrieve all items associated with the Shipping Templates.

Step 1: Send request body with all SKUs

To get the shipping template and fulfillment center associated with each item SKU, provide a list of all item SKUs in the body of the request. For example, call POST /v3/items/associations

For an example request body, see Request Samples in the Get Item Associations API Reference.

Note: The maximum number of item SKUs you can pass in one request is 50.

Step 2: View Shipping Templates for each item SKU

The response returns all Shipping Templates associated with that item SKU, including the Shipping Template, and the Fulfillment center (i.e. Ship Node).

For each Shipping Template assigned to a SKU, the response provides:

• shippingTemplate
  • name – Specified by seller (e.g. “2Day – MidWest region”)
  • type – One of the type values: CUSTOM, DEFAULT or DELIVERR.
  • id – Shipping Template identifier specified by seller.

• shipNodeName – Seller-specified Fulfillment Center name (e.g. “MP_Deliverr.”)
• shipNode – Walmart-specified Fulfillment Center (aka “Ship Node”) identifier.

For an example response, see Response Samples in the Item Associations API Reference.

Existing Direct Fit Items can be updated for Fitment Data via the Bulk Item Update API for Feed Types FITMENT_ACES and FITMENT_PIES

Both ACES and PIES XML file types should be uploaded in .zip format. The .zip files can only contain one file type and one brand at a time and should be no larger than 10 MB. See below for more specific rules per file type. 

ACES files 

• The BrandAAIAID must be present in the header row of the file. 
• The BrandAAIAID must be present in the BrandAAIAID tag for the first 1,000 characters of the file (ex. <BrandAAIAID>(Brand ID)</BrandAAIAID>).
• Values must be present for the BaseVehicleID, PartNumber, and PartTerminologyID.
• To add a new vehicle, the action value should be equal to ‘Add’ (A).
• To delete an existing vehicle, the action value should be equal to ‘Delete’ (D).
• If an action value is missing for an XML app node, the value will default to ‘Add’ (A).
• If the SubModel/EngineBase value is empty, the value will default to ‘All’ meaning the products fits all types. 

 PIES files 

• Values must be present for the ItemLevelGTIN, BrandAAIAID,PartNumber, and Part TerminologyID.  
• Items will be updated only if there is a change in attribute values corresponding to a particular GTIN and the MaintenanceType value is ‘Add’ (A) or ‘Change’ (C).  

Example .zip files:

• ACES_Sample_File.zip
• PIES_Sample_File.zip

 **NOTE: If any of the rules above are not followed, the file will not be processed and will return an error. In some situations, after uploading your files, an attribute may not reflect the update based on the content ranking source. 

Once the feed has been processed, the Feed Item Status API will return the status of the feed. Incase of errors use Error Download API to download the error report.