Marketplaces / Walmart / Walmart Product Management / Walmart Product Listing OLD

Walmart Product Listing OLD

Summary of Changes: (The purpose of this table is to keep traceability and Product team to highlight the things that were changed into the scope, based on comments or discussions)

Version	Date	Created / Updated	Notes
v1.0	N/A	Danail	First publish
v1.1	14/12/2023	Hristiyan	Walmart has new API version and updates. The scope was also updated to the latest changes on Walmart. Everything that is not tagged with v1.1 remains the same.
v1.2	12/02/2024	Hristiyan	Added logic for images handling and triggers
v1.3	13/02/2024	Hristiyan	Added logic for the start/end date
v1.4	10/04/2024	Hristiyan	Updated schema & mapping
v1.5	16/04/2024	Hristiyan	Added clarification about the IsPrimaryVariant
v1.6	29/04/2024	Hristiyan	Added logic for SKU and Product ID update.

This page is to define general requirements for Walmart listing creation and maintenance

<v1.1>API Docs: https://developer.walmart.com/api/us/mp/feeds & https://developer.walmart.com/api/us/mp/items#operation/itemBulkUploads </v1.1>

API Call: POST /v3/feeds

<v1.4> TYPES: MP_ITEM & MP_MAINTENANCE & OMNI_WFS

We have 3 things we need to do, create and update the product information and convert an existing product to a WFS which is happening with three different type of feeds that also go through different schema version validations. For phase 1 we want to only do the create and update products. The WFS convertion will be done at phase2.

PRODUCT CREATE

MP_ITEM_SPEC_4.8.json

Below is an example payload for the feed followed by Hemi mapping

{
  "MPItemFeedHeader": {
    "sellingChannel": "marketplace",
    "processMode": "REPLACE",
    "subset": "EXTERNAL",
    "locale": "en",
    "version": "4.8",
    "subCategory": "home_other"
  },
  "MPItem": [
    {
      "Orderable": {
        "sku": "testCardSku",
        "productIdentifiers": {
          "productIdType": "GTIN",
          "productId": "06146190200012"
        },
        "productName": "Ying Yang Apron, Abstract Graphic Design Yin Yang Circle Black and White Dots Pattern Cosmos and Energy, Unisex Kitchen Bib with Adjustable Neck for Cooking Gardening, Adult Size, Red, by Ambesonne",
        "brand": "davidson",
        "price": 1,
        "ShippingWeight": 1,
        "MustShipAlone": "No"
      },
      "Visible": {
        "Computers": {
        "shortDescription": "Frame Material: Acetate Lens Material: Demo Lens Width: 52mmFrame Material: Acetate Lens Material: Demo Lens Width: 52mmFrame Material: Acetate Lens Material: Demo Lens Width: 52mmFrame Material: AceFrame Material: Acetate Lens Material: Demo Lens Width: 52mmFrame Material: Acetate Lens Material: Demo Lens Width: 52mmFrame Material: Acetate Lens Material: Demo Lens Width: 52mmFrame Material: AceFrame Material: Acetate Lens Material: Demo Lens Width: 52mmFrame Material: Acetate Lens Material:",
       "mainImageUrl": "https://i5-qa.walmartimages.com/asr/af93a111-934e-450c-bd94-9a747a72e415.e6d8c62517a21d945bd8e6dd38f3a0af.jpeg",
          "productSecondaryImageURL": [
            "https://i5.walmartimages.com/asr/d67dfccc-3ffc-4752-ae10-b25cd587c7a9.e6d8c62517a21d945bd8e6dd38f3a0af.jpeg"
          ],
          "count": "MFP00112BBQNMFP00112BBQNMFP00112BBQNMFP00112BBQNM",
          "msrp": 12345.98,
          "manufacturer": "MFP00112BBQNMFP00112BBQNMFP00112BBQNMFP00112BBQNMFP00112BBQ",
          "manufacturerPartNumber": "DeagoDeagoDeagoDeagoDeagoDeagoDeagoDeagoDeagoDeagoDeagoDeag",
          "color": [
            "Green"
          ],
          "colorCategory": [
            "Green"
          ],
          "keyFeatures": [
            "@generated"
          ],          
          "features": [
            "Frame Material: Acetate Lens Material: Demo Lens Width: 52mmFrame Material: Acetate Lens Material: Demo Lens Width: 52mmFrame Material: Acetate Lens Material: Demo Lens Width: 52mmFrame Material: AceFrame Material: Acetate Lens Material: Demo Lens Width: 52mmFrame Material: Acetate Lens Material: Demo Lens Width: 52mmFrame Material: Acetate Lens Material: Demo Lens Width: 52mmFrame Material: AceFrame Material: Acetate Lens Material: Demo Lens Width: 52mmFrame Material: Acetate Lens Material:"
          ],                
          "modelNumber": "TSR1002TSR1002TSR1002TSR1002TSR1002TSR1002TSR1002TSR1002345",

          "prop65WarningText": "Frame Material: Acetate Lens Material: Demo Lens Width: 52mmFrame Material: Acetate Lens Material: Demo Lens Width: 52mmFrame Material: Acetate Lens Material: Demo Lens Width: 52mmFrame Material: AceFrame Material: Acetate Lens Material: Demo Lens Width: 52mmFrame Material: Acetate Lens Material: Demo Lens Width: 52mmFrame Material: Acetate Lens Material: Demo Lens Width: 52mmFrame Material: AceFrame Material: Acetate Lens Material: Demo Lens Width: 52mmFrame Material: Acetate Lens Material:",
          "warrantyText": "This warranty covers any defects in materials or workmanship, including installation, with the exceptions of fading or discoloration caused by exposure to sunlight or chemicals. This warranty runs for five years from the date your carpet is installed. Counterpoint will either replace your carpet with new carpet of similar composition and price, or refund the full purchase price of your carpet, whichever you prefer. Contact Counterpoint at 800-867-5309... [continued]."

               }
      }
    }
  ]
}

Mapping (please note the mapping is based on the example. As a follow information please see a general breakdown of the schema)

Walmart field				Hemi Mapping	Hemi Notes
`MPItemFeedHeader`				N/A
	`sellingChannel`			N/A	Hardcoded “marketplace”
	`processMode`			N/A	Hardcode this as “REPLACE”
	`subset`			N/A	Hardcoded “EXTERNAL”
	`locale`			N/A	Hard coded “en”
	`version`			NA	To be picked from the latest Schema being used
`MPItem`
	`Orderable`
		`sku`		`Product` > `SKU`
		`productIdentifiers`
			`productId`	`Product` > `EAN`

OR Product >UPC OR Product >ISBN | We should pick one of the 3 in that priority order and present it in the required format of key [mapped to productIdType] and value [mapped to productId] | | | | | productName | | Product Account > Title | | | | | | brand | | Product Account > Item Specifics OR Product > Brand | If the attribute “Brand” is required in the taxonomy we pick it from Product Account > Item Specifics

If the attribute “Brand” is not present in the taxonomy we pick it from Product > Brand

<v1.2> All validations triggers etc. are as per the Images abstraction - Images Handling Additional Explanation </v1.2> | | | | | | productSecondaryImageURL | Product Account Walmart > Additional Images OR Product > More Picture URLs | Product Account Walmart > Additional Images is with priority. Based on the explanation of the JSON schema it seems to be an Array field so we should be able to fit in all our additional images for the product.

</v1.4>

As there are a lot of additional fields based on the JSON schema for product creation we will focus on specific fields within the “Visible” and “Orderable” and general view of all other fields and their handling and picking

Headers - In further inspection of the options of the headers within the feed itself I don’t believe it is necessary to use any of them. If it will help in any way we can use request IDs and dates to potentially keep track of them further if we want to

Below the required fields as per the schema:

"required": [
                "subset",
                "locale",
                "sellingChannel",
                "processMode",
                "version"
            ]

Orderable - This section is what we can call the main section of the product including identifiers, prices, names, brands etc. The most common information (almost the way we’ve split it between our Item and Item Account). Besides the above specified mappings worth specific mentioning here is that we will NOT support Multipacks with their specific pricing and quantity or Price per unit of measurement for stat.

<v1.4>Below the required fields as per the schema:

"required": [
                            "", 
                            "brand", 
                            "productName", 
                            "ShippingWeight", 
                            "productIdentifiers", 
                            "price"

</v1.4>

Visible - This section is what we can define as the “listing” - it holds specific information, attributes, images, variant groupings, etc. to be able to represent the actual item as best as possible to the general public. Besides the required and mapped from above fields below a few more that we should either add in item_account_walmart or just have in mind for mapping:

Walmart field	Hemi Mapping	Hemi Notes
`labelImage`	`Product Account Walmart` > `Label Image`	Very specific shot of the label of the product. Not mandatory but if and when present can boost sales a lot
`productSecondaryImageURL`	`Product Account Walmart` > `More Picture URLs`

OR `Product` > `More Picture URLS`	Based on the explanation of the JSON schema it seems to be an Array field so we should be able to fit in all our additional images for the product
`variantAttributeNames`	`Product Account` > `Variation Specifics`	Each category has different things by which a product can vary in Walmart. This should be part of the validations as per the schema but also by this field we select which attributes in reality are to be used as variations for this product variation. Essentially all information for the product (for example Colour and Size) are treated as “Attributes” for Walmart and then it is selected based on the allowed enums for the Category by which attribute should this product vary. I haven’t seen a limit by how many things a product can Vary but we want to limit it to 4 in Hemi (if there are more than 4 VariationSpecifics we want to stop the product). The additional validation enforced by Walmart is 100 products in a single variation or 500 products in a multi variation. In case we hit those we want to stop the product creation again with the relevant error message
`isPrimaryVariant`	`Product Account Walmart` > `Primary Variant`	The selected primary variant is the one that will be displayed on Walmart when grouping and showing the whole variation. The recommendation is to use the best selling item to maximise gains. We want to give the option to our users to select their primary variant for each variation. There can be only one Primary variant per variation! If multiple are selected this is an internal error. If none is selected this field should NOT be specified and at this point Walmart will automatically pick and assign “Primary” on the first product
<v1.5> Default value should be No and we should exclude it from the payload if it is on default value.</v1.5>
`swatchImages`	`Product Account Walmart` > `Swatch Images`	A key value type of field. Swatch Images are basically samples and the way to select a specific Image to be displayed for a specific variant option on selection. If no such are applied Walmart will display the variation option as a simple tile. The key should be a designated Variation key (example: colour) [Mapped to `swatchVariantAttribute`] and the value the image we want to display for that specific product [Mapped to `swatchImageUrl`]. It can hold multiple images as Swatch Images can be provided for more than one variation option

Below the required fields as per the schema:

"required": [
                                    "shortDescription",
                                    "mainImageUrl"

                                ]

</v1.1>

Additional specifications:

Walmart is a single step feed creation - meaning once we push the product with all necessary information it should directly be available to the buyers for purchase (if successful of course)
Everything else not specified above as part of the feed should be part of the Item Specifics to define the product requirements
We should think on general best practice to normalise fields from Item Account > Item Specifics so we don’t have to force people to input their information specifically in Camel case
Every Walmart feed is featuring 1 category - I am almost 100% sure this is how it is to be used via API as well when it goes through their UI and an excel template is uploaded

<v1.1> PRODUCT UPDATE

MP_MAINTENANCE_SPEC_4.8.json

Below is an example payload for the feed followed by Hemi mapping

{
  "MPItemFeedHeader": {
    "sellingChannel": "mpmaintenance",
    "processMode": "REPLACE",
    "subset": "EXTERNAL",
    "locale": "en",
    "version": "4.8",
    "subCategory": "computers"
  },
  "MPItem": [
    {
      "Orderable": {
        "sku": "skum1_may23_fail01_test",
        "productIdentifiers": {
          "productIdType": "GTIN",
          "productId": "06848390988881"
        },
        "productName": "iPhone 14 pro max",
        "brand": "Apple",
        "price": 299.99,
        "startDate": "2023-05-23T07:00:00Z",
        "endDate": "2049-12-31T08:00:00Z",
        "shipsInOriginalPackaging": "No",
        "MustShipAlone": "No",
        "ShippingWeight": 4
      },
      "Visible": {
        "Computers": {
          "shortDescription": "test Desc fold",
          "mainImageUrl": "https://i5-qa.walmartimages.com/asr/7bec61bc-ec33-4334-8131-ecb8305e1e19.62d73c2f61f929ef580fe375e3597c13.jpeg",
          "keyFeatures": [
            "@generated"
          ]
        }
      }
    }
  ]
}

Mapping (please note the mapping is based on the example. As a follow information please see a general breakdown of the schema)

Walmart field				Hemi Mapping	Hemi Notes
`MPItemFeedHeader`				N/A
	`sellingChannel`			N/A	Hardcoded as “`mpmaintenance`”
	`processMode`			N/A	Hardcoded as “REPLACE”
	`subset`			N/A	Hardcoded as “EXTERNAL”
	`locale`			N/A	Hardcoded as “en”
	`version`			N/A	To be picked from the latest Schema being used
	`subCategory`			`Product Accoun`t > `Primary Category ID`	One feed per Category (*see additional information below)
`MPItem`
	`Orderable`
		`sku`		`Product` > `SKU`
	`productIdentifiers`			We should pick one of the 3 in that order and present it in the required format of key [mapped to `productIdType`] and value [mapped to `productId`]
			`productIdType`	`Product > EAN`

`ORProduct >UPC` `OR` `Product >ISBN`	We should pick one of the 3 in that priority order and present it in the required format of key [mapped to `productIdType`] and value [mapped to `productId`]					`productId`	N/A	This should be either `EAN` or `UPC` or `ISBN` depending on which one we are sending.				`productName`		`Product Account` > `Title`					`brand`		`Product Account` > `Item Specifics` OR `Product` > `Brand`	`Product Account` > `Item Specifics` is with priority				`price`		`Product Account` > `Start Price`					`startDate`		`Product Account Walmart` > `Start Date`	If not present - NOW
	`endDate`		`Product Account Walmart` > `End Date`	If not present - NOW+2 years

<v1.3>We want to have a validation and we should not be able to have End Date bigger than the Start Date</v1.3> | | | | shipsInOriginalPackaging | | N/A | | | | | MustShipAlone | | N/A | | | | | ShippingWeight | | <v1.4> Product > Weight | This is a required field as per the schema. We want to have a validation and if we don’t have weight for the given product, we want to return internal error. As per schema the weight needs to be send in pounds and in Hemi we keep it in grams so we need to convert it.</v1.4> | | | Visible | | | | | | | | Computers | | Product Account > Primary Category ID | | | | | shortDescription | | Product Account > Description | | | | | mainImageUrl | | Product Account Walmart > Main Image OR Item > Main Image | Product Account Walmart > Main Image is with priority

<v1.2> All validations triggers etc. are as per the Images abstraction - Images Handling Additional Explanation </v1.2> | | | | keyFeatures | | Product Account > Item Specifics | Just random IS for the category |

<v1.6> Product SKU and Product ID update

Walmart are allowing us to update SKU and Product ID and for this we need to send specific attribute in the payload based on a trigger in Hemi. We need to send the feed with feedType = MP_ITEM and sellingChannel= ‘marketplace’ (basically the SKU and Product Updates are considered as “item creation” and we need to use the feed type and payload for product create)

We will need a new internal feed type which should be named “Listing SKU/ID update”. We will need this new type in order to distinguish the different feeds that are being sent to walmart.

The field attributes are as follows and they need to be in the “Orderable” section :

"SkuUpdate": "Yes",
"ProductIdUpdate": "Yes"

Mapping :

Walmart Field	Hemi Mapping	Notes
`SkuUpdate`	`Product Account Walmart` > `Update SKU`	This is a checkbox field. If the checkbox is not checked, we exclude it from the payload.
If it is checked, we send the field in the payload with value “Yes”
`ProductIdUpdate`	`Product Account Walmart` > `Update GTIN`	This is a checkbox field. If the checkbox is not checked, we exclude it from the payload.
If it is checked, we send the field in the payload with value “Yes”

We want to still stick to abstraction rules and if we have a product for sku update from a variation, we push the whole variation but only add the UpdateSku attribute in the payload for the relevant product. We want to treat the UpdateSku flow with priority meaning that if we have a variation where a product is due to be updated and then another product from the same variation that is due to have SKU update, we should pick the SKU update first, send the update and then raise the List/Update field to Pending again so we can send the standard update.

After successful update, we want to update the Product Account Walmart >Update SKU or Product Account Walmart > Update GTIN (depending which was sent for update) and uncheck the field. If there was an error we want to store it as per the Listing Update abstraction

Product Listing general requirements

</v1.6>

</v1.1>

Also please note that required fields in MP_MAINTENANCE step are different (a lot less) than in MP_ITEM. This is due to the general expectation of Walmart that through the Maintenance step we are passing only updates to changed fields (example payload above).

<v1.4> WFS Convention (phase2)

Walmart are much like Amazon where you as a seller can sell and fulfill your own items or you could ship your inventory to a Walmart Fulfillment Centre and they handle the shipping for you. We are able to list products only for seller fulfillment and for both seller and walmart fulfillment. The second is done via the OMNI_WFS feed type.

ConvertSpecSchema_v1.3.json

Below is an example payload for the feed followed by Hemi mapping

{
  "SupplierItemFeedHeader": {
    "locale": "en",
    "mart": "WALMART_US",
    "processMode": "REPLACE",
    "requestBatchId": "1677739858",
    "requestId": "1677739858",
    "sellingChannel": "fbw",
    "subCategory": "clothing_other",
    "subset": "EXTERNAL",
    "version": "4.5"
  },
  "SupplierItem": [
    {
      "Orderable": {
        "batteryTechnologyType": "Does Not Contain a Battery",
        "brand": "Jane + Vogue",
        "chemicalAerosolPesticide": "No",
        "electronicsIndicator": "No",
        "endDate": "2033-03-02T00:00:00.694Z",
        "price": 51.66,
        "productIdentifiers": {
          "productId": "testProductId",
          "productIdType": "GTIN"
        },
        "productName": "PLEATED SKORT",
        "sku": "testSku",
        "stateRestrictions": [
          {
            "stateRestrictionsText": "None"
          }
        ]
      },
      "TradeItem": {
        "countryOfOriginAssembly": [
          "US - United States"
        ],
        "each": {
          "eachDepth": 5,
          "eachGTIN": "",
          "eachHeight": 5,
          "eachWeight": 1,
          "eachWidth": 5
        },
        "orderableGTIN": "testGtin",
        "sku": "testSku"
      },
      "Visible": {
        "Clothing": {
          "ageGroup": [
            "Teen",
            "Adult"
          ],
          "clothingSize": "S",
          "color": [
            "WASHED BLACK"
          ],
          "colorCategory": [
            "Black"
          ],
          "countryOfOriginTextiles": "USA",
          "gender": "Female",
          "mainImageUrl": "http://cdn.shopify.com/s/files/1/0625/1770/6943/products/15442152_61f353b2-b8ec-45f8-9129-b6ced177a851.jpg?v=1661089729",
          "manufacturer": "Jane Vogue",
          "productSecondaryImageURL": [
            "http://cdn.shopify.com/s/files/1/0625/1770/6943/products/15442152_7be883c4-fb3c-45a6-8123-f0968ca51bde.jpg?v=1661089724",
            "http://cdn.shopify.com/s/files/1/0625/1770/6943/products/15442152_15a9416a-14c1-499d-b299-d85eb9e8b804.jpg?v=1661089725",
            "http://cdn.shopify.com/s/files/1/0625/1770/6943/products/15442152_be74fd10-94ab-4597-8d4f-10b5f07d207b.jpg?v=1661089728",
            "http://cdn.shopify.com/s/files/1/0625/1770/6943/products/15442152_095a37fa-a2e9-4495-8f67-17c231bdd4e0.jpg?v=1661089733"
          ],
          "prop65WarningText": "None",
          "smallPartsWarnings": [
            "0 - No warning applicable"
          ]
        }
      }
    }
  ]
}

Mapping is **TBA

</v1.4>**

Attention: This might not be the case but we must make sure that when updating full information (even if it didn’t change) this is not going to break anything on the listing itself on Walmart from the perspective of pricing and Quantity (offer). Walmart’s general expectation is that we should be updating only what is changed through the maintenance but we don’t operate this way - we send always the full info. I believe this shouldn’t be an issue since we are using versions 4+ for any creations and updates, still it is worth mentioning and having in mind

Is this article helpful?

0 0 0