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.

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. To learn about how to group items, see Variant Setup.

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.

About item spec versions

The Marketplace APIs provide two item spec versions: item spec v3.2 and v4.2. The legacy version v3.2 does not provide the enhanced setup workflow, and other improvements. We recommend that you use the new optimized Item spec v4.2 to take advantage of improvements.

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. To learn about how to group items, see Variant Setup.

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"
}

Optimized Item setup and maintenance with Item Spec 4

Item spec v4 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.

To take advantage of the new item management efficiency, make sure to use the Item 4.2 spec and new feed types when you do your initial setup with the Bulk item setup API.

About item spec versions

The Marketplace APIs provide two item spec versions: item spec v3.2 and v4.2. The legacy version v3.2 does not provide the enhanced setup workflow, and other improvements. We recommend that you use the new optimized Item spec v4.2 to take advantage of improvements.

To take advantage of the new item management efficiency, make sure to use the Item 4.2 spec and new feed types when you do your initial setup with the Bulk item setup API.

The new Item spec v4 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, and 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 is available in JSON schema format only for better ease of use.

Changes in Spec v4.4

• – The Items API now supports the ability to submit Multiple Category Specs dynamically in Seller Center.
• – The baby_clothing sub-category has been removed. Please use clothing or footwear spec sub-categories instead.
• – The following attributes were removed from Vehicle Parts & Accessories: Vehicle Year, Vehicle Make, and Vehicle Model.
• – Added Fit Type to the Vehicle Parts and Accessories sub-category.
• – The ProductTaxCode attribute has been removed.

Item Specs v4

• To create new items for Walmart only: MP_ITEM_SPEC_4.4.json
  Use feedType=MP_ITEM
• To create new items for Walmart and WFS: MP_WFS_ITEM_SPEC_4.2.json
  Use feedType=MP_WFS_ITEM
• To change or update an existing item: MP_MAINTENANCE_SPEC_4.4.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.4.json
Use feedType=OMNI_WFS

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

The legacy item spec v3.2 contains one set of XSDs that represents an item object i.e., MPitem object.

• To use Item XSDs:  V3-Spec-MarketPlace-Items-3.2-XSD.zip
  Use feedtype=item
• To use Item JSON schemas:  V3-Spec-MarketPlace-Items-3.2-JSON.zip
  Use feedtype=item

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.

Item setup steps

1. Send an item feed to Walmart with payload in either XML or 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. A typical strategy for fixing an error is to first check the XML against the XSDs and then create a case for Partner Support.
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.

Keep feed sizes below 10 MB to ensure optimal feed processing time.

Item spec feed types and versions

You can use any Item spec version you prefer. Make sure to use the associated feed type for the version you want to use:

• Item spec 3.2 feed type: item
• Item spec 4.1 feed types: MP_WFS_ITEM or MP_MAINTENANCE
• Item spec 4.2 feed type: MP_ITEM

For more information about which spec to download for each feed, see Items > Bulk item setup.

New requirement for WFS items: Restrict item sale by geographic location

There is a new requirement for setting up items 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.”

For more details about the State Restrictions attribute and its usage, see Restrict item sale by state or zip code.

Set up items that match Walmart items

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.

This section outlines a possible implementation plan as described in the Item Management API Overview.

1. Walmart item client-side status
2. Send items for ingestion
3. Check ingestion status
4. Check published status
5. Correct item errors

Walmart item client-side status

For this implementation, we assume that you will use your own client-side database to store the status of your items and feeds on Walmart.mx. A possible set of statuses could be:

Status	Description	Comment
transmit	To be transmitted to Walmart	Can be set to this state by seller deciding to include SKU on Walmart.com, or by system requesting a re-transmission because data errors were detected and fixed
data fix	Schema or content is incompatible with Walmart.com	Check the item XML file against the XSD file
ingestion in progress	Item is in the ingestion process	No updates allowed at this time
publish in progress	Item is in publishing process	Ingestion is completed, but publishing must be completed before you can add inventory
published	Item is published on Walmart.com	Inventory can be added and the item can be sold to customers
system error	An error was encountered during publishing	Contact Walmart Marketplace Support
unpublished	Not available on Walmart.com	Usually caused by the removal of an item
data fix – ticket	Support ticket submitted	Underlying error status is data fix
system error – ticket	Support ticket submitted	Underlying error status is a system error

Send items for ingestion

This flow describes how you may want to send your items to Walmart and process immediate errors. On an initial ingestion, the object used must be the MPItem object; thereafter, you may use the OfferEnvelope or the ProductEnvelope object.

Check ingestion status

The flow below describes how you may monitor the status of your items as they are ingested.

Check published status

The flow below describes how you may monitor the status of your items as they move through the publishing process.

Correct Item Errors

The flow below describes how you may implement a process for correcting item errors. In addition to the flow below, you may want to build your own process for correcting items and their statuses as Walmart Marketplace Support responds to support tickets.

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

Process Mode

The process mode is used to identify what action a user needs to perform for a given item. The supported values for the process mode is listed in the table below.

The following table describes each process mode:

Process Mode	Description	Element Required	Notes
CREATE	Creates a new item.	MPProduct and MPOffer	An error will occur if the request is sent with only MPProduct element
REPLACE_ALL	Replaces MPProduct and MPOffer information	MPProduct or MPOffer	The default value is the MPProduct element
PARTIAL_UPDATE	Merges the contents of item	MPProduct	An error will occur if the request is sent with the MPOffer element

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.