Walmart Taxonomy

The purpose of this document is to define the standards of how how to work with Walmart Taxonomy

Walmart has updated their taxonomy which is different enough so that we create a brand new flow from scratch.

Taxonomy Validation and Product Optimization

The structure of the Walmart taxonomy is they have the main category, followed by a 2nd level category which then could have many leaf categories. So for example the structure would be main category > category > leaf category. Every leaf category is described through a JSON schema and we must validate against that particular schema.

Also they have Orderable and Visible attributes and DO support sub-attributes structure.

In order to comply with all the specifics we will need to first get all the available categories through a get taxonomy call.

Get Taxonomy

API Call : GET https://marketplace.walmartapis.com/v3/items/taxonomy?version=5.0.20250121-19_24_23-api

API Docs: https://developer.walmart.com/us-marketplace/reference/gettaxonomyresponse

We want to use a parameter version with value = 5.0.20250121-19_24_23-api (this is the latest version as of now)

Sample Response (200):

{
    "itemTaxonomy": [
        {
            "description": "Beauty",
            "category": "Beauty",
            "productTypeGroup": [
                {
                    "productTypeGroupName": "Body Makeup",
                    "description": "Body Makeup",
                    "productType": [
                        {
                            "productTypeName": "Henna Stencils",
                            "description": "Henna stencils are thin sheets of paper, cardboard, plastic, or metal with a pattern or letters cut out of it, used to produce the cut design on the surface below it by the application of henna dye through the holes."
                        },
                        {
                            "productTypeName": "Temporary Tattoos",
                            "description": "Temporary tattoos are decorative images that can be applied to the skin for short periods of time. Most temporary tattoos are novelty items made with a special type of decal. A process known as screen printing is used to create the tattoo image on paper coated with a transfer film. The transfer film allows the image to \"\"slide\"\" off the backing paper and onto the skin when moisture is applied. After drying, the film holds the image on the skin through several washings.;Another form of ink used in temporary tattoos is henna.  Therefore, henna body art is some times referred to as \"\"temporary tattoos\"\"."
                        },
                        {
                            "productTypeName": "Body Glitter",
                            "description": "Body glitter is a form of body paint.  It is an assortment of small, reflective particles that come in a variety of shapes, sizes, and colors that is applied to parts of the body. The glitter particles reflect light at different angles, causing the surface of the skin to sparkle or shimmer. It is similar to confetti, sparkles, or sequins, but somewhat smaller and is applied to the body using a bonding agent, like special glue or petrolium jelly."
                        },
                        {
                            "productTypeName": "Henna Paste & Powder",
                            "description": "Henna paste is derived from the leaves of the plant which is ground to a fine powder and then mixed with various liquids to achieve the desired consistency for application.  Used for temporary henna tattoos/markings and for dyeing hair."
                        },
                        {
                            "productTypeName": "Henna Body Art Kits",
                            "description": "Henna body art kits are pre-collated bundles that contain all the things needed to apply henna dye to the skin.  Jagua Ink falls under this PT too.;Example: HENNA KIT;* 50 grams of our exclusive Supreme Blend Henna Powder;* 5ml bottle of our Red Raj Bliss Blend essential oil;* 50 grams of fructose sugar;* 1 jacquard applicator bottle with 1 metal tip (size .5mm);* 1 hand rolled cone with elastic band;* 20 alcohol wipes;* 1 2oz empty spray bottle;* 1 henna tool kit;* 2 full pages of henna designs ;* Instructions and recipe;* Comes with zipper pouch"
                        },
                        {
                            "productTypeName": "Body Paint",
                            "description": "Body paint is a colored substance which is spread over the whole, or part of the, body for decoration.  It is specially made for the human skin and is safe. Unlike tattoos and other forms of body art, body painting is temporary, lasting several hours or sometimes up to a few weeks. Body painting that is limited to the face is known as \"face painting\". Body painting is also referred to as (a form of) \"temporary tattoo\". Large scale or full-body painting is more commonly referred to as body painting, while smaller or more detailed work can sometimes be referred to as temporary tattoos.  Henna is a form of body paint, but is seldom referred to as body paint."
                        },
                        {
                            "productTypeName": "Henna Applicators",
                            "description": "Henna applicators are tools used to apply henna dye to the skin.  **See definition of \"henna\" below.\n\nHenna is a dye prepared from the plant Lawsonia Inermis, also known as the henna tree, the mignonette tree, and the Egyptian privet. Henna can also refer to the temporary body art resulting from the staining of the skin from the dyes. After henna stains reach their peak color, they hold for a few days, then gradually wear off by way of exfoliation, typically within one to three weeks."
                        },
                        {
                            "productTypeName": "Tattoo & Piercing Aftercare",
                            "description": "Tattoo & Piercing Aftercare are the steps one needs to take, or the products one needs to apply, after getting a tattoo and/or piercing to prevent infection or undesired effects.;Example: TATTOO AFTERCARE;* Leave bandage on for 1-2 hours.;* Remove bandage and wash immediately with a fragrance free anti-bacterial or anti-microbial soap and warm water.;* Apply Tattoo Goo Lotion, liberally to area 15 minutes before sun exposure.;* Pat dry with a clean paper towel or let air dry for 30 minutes."
                        }
                    ],
                    "department": [
                        {
                            "departmentName": "BEAUTY",
                            "departmentNumber": "46"
                        },
                        {
                            "departmentName": "SPORTING GOODS",
                            "departmentNumber": "9"
                        },
                        {
                            "departmentName": "SEASONAL",
                            "departmentNumber": "18"
                        },
                        {
                            "departmentName": "MENS WEAR",
                            "departmentNumber": "23"
                        },
                        {
                            "departmentName": "LADIES ACCESSORIES/HANDBAGS",
                            "departmentNumber": "31"
                        },
                        {
                            "departmentName": "JEWELRY - SUNGLASSES",
                            "departmentNumber": "32"
                        },
                        {
                            "departmentName": "GIRLS WEAR",
                            "departmentNumber": "33"
                        },
                        {
                            "departmentName": "LADIES WEAR",
                            "departmentNumber": "34"
                        }
                    ]
                },
                {
                    "productTypeGroupName": "Beauty Storage & Organization",
                    "description": "Beauty Storage and Organization",
                    "productType": [
                        {
                            "productTypeName": "Makeup Bags",
                            "description": "Soft-sided bag intended to carry makeup, usually for travel."
                        },
                        {
                            "productTypeName": "Makeup Organizers",
                            "description": "Organizer rack or container that holds makeup, brushes, and other cosmetic items."
                        },
                        {
                            "productTypeName": "Makeup Cases",
                            "description": "A hard-sided case for makeup, usually geared toward professionals."
                        },
                        {
                            "productTypeName": "Hair Dryer Stands",
                            "description": "Hair dryer stand is for setting an operating blow-dryer on a countertop and without burning the countertop or material on the countertop"
                        }
                    ],
                    "department": [
                        {
                            "departmentName": "PERSONAL CARE",
                            "departmentNumber": "2"
                        },
                        {
                            "departmentName": "BEAUTY",
                            "departmentNumber": "46"
                        },
                        {
                            "departmentName": "LADIES ACCESSORIES/HANDBAGS",
                            "departmentNumber": "31"
                        },
                        {
                            "departmentName": "JEWELRY - SUNGLASSES",
                            "departmentNumber": "32"
                        }
                    ]
                },
                {
                    "productTypeGroupName": "Mixed Makeup Sets",
                    "description": "Mixed Makeup Sets",
                    "productType": [
                        {
                            "productTypeName": "Makeup Sets",
                            "description": "Makeup Sets are complete products that are comprised of predominantly different makeup items, but sold as one unit. This could include any combination of makeup, from lipsticks to eyeshadows, concealers, foundations, blushes, etc. Some makeup sets include application brushes, sponges, and/or a case of some sort. Typically, these are all the same brand or product line, sold as one unit."
                        },
                        {
                            "productTypeName": "Makeup Palettes",
                            "description": "Makeup Palettes offer a set or range of makeup shades/colors in one container as part of a collection of cosmetics. Most palettes tend to include similar colors that play well together, but can also be used for color correcting. Makeup palettes are often just used in eye shadow, color correcting powders/foundations, blushes, bronzers and highlighter cosmetics. It is sold as one unit because the palette is one item (as opposed to several items like in Makeup Sets). This is not a \"set\" because it is one container. However, if it is sold with other items like brushes, lipsticks, etc, then it should be classified in the Makeup Sets PT."
                        }
                    ],
                    "department": [
                        {
                            "departmentName": "BEAUTY",
                            "departmentNumber": "46"
                        },
                        {
                            "departmentName": "SEASONAL",
                            "departmentNumber": "18"
                        }
                    ]
                },
                {
                    "productTypeGroupName": "Lip Products",
                    "description": "Lip Products",
                    "productType": [
                        {
                            "productTypeName": "Lip Plumpers",
                            "description": "Lip plumpers work by holding onto moisture in the skin surface, which results in a localized swelling effect. This gives the lips a fuller and smoother appearance."
                        },
                        {
                            "productTypeName": "Lip Scrubs",
                            "description": "A lip scrub is a semi-liquid or other soft-solid base containing particles that slough off dry, flaky pieces and leave smooth skin behind on lips."
                        },
                        {
                            "productTypeName": "Lip Glosses",
                            "description": "Lip gloss is a product used primarily to give lips a glossy lustre, and sometimes to add a subtle color. It is distributed as a liquid or a soft solid."
                        },
                        {
                            "productTypeName": "Lip Balms & Conditioners",
                            "description": "Lip balm or lip salve is a wax-like substance applied topically to the lips to moisturize and relieve chapped or dry lips, angular cheilitis, stomatitis, or cold sores.  Products made to condition and moisturize the lips.  Can be a balm, a medicated balm, a sleeping mask or ointment."
                        },
                        {
                            "productTypeName": "Lip Stains",
                            "description": "Lip stain is a cosmetic product used to color the lips, usually in form of a liquid or gel. It generally stays on longer than lipstick by leaving a stain of color on the lips."
                        },
                        {
                            "productTypeName": "Lip Liners",
                            "description": "Lip liner, or lip pencil, is a product intended to fill in uneven areas on the outer edges of the lips before applying lipstick to give a smoother shape."
                        },
                        {
                            "productTypeName": "Lipsticks",
                            "description": "Lipstick is a cosmetic product containing pigments, oils, waxes, and emollients that apply color, texture, and protection to the lips."
                        },
                        {
                            "productTypeName": "Lip Primers",
                            "description": "Lip primers are put on the lips under other prodiucts to create a smooth canvas for flawless coverage. And if chosen correctly, lip primer has the ability to nourish lips, prevent feathering, provide long-lasting lip color, and add dimension to your shade of choice."
                        }
                    ],
                    "department": [
                        {
                            "departmentName": "BEAUTY",
                            "departmentNumber": "46"
                        },
                        {
                            "departmentName": "IMPULSE MERCHANDISE",
                            "departmentNumber": "82"
                        },
                        {
                            "departmentName": "SEASONAL",
                            "departmentNumber": "18"
                        },
                        {
                            "departmentName": "LADIES ACCESSORIES/HANDBAGS",
                            "departmentNumber": "31"
                        },
                        {
                            "departmentName": "JEWELRY - SUNGLASSES",
                            "departmentNumber": "32"
                        }
                    ]
                }
            ]   
        }
    ],
    "status": "OK"
}

Please note that this response has been modified to show just a few categories as the full response is too big, the full one can be found here :

walmart-taxonomy2.json

Once we have received all the available categories we need to call each leaf category (productTypeName) and retrieve the specific JSON schema for the specific category thoguh a get item spec call :

Get Item Spec

API Call : POST https://marketplace.walmartapis.com/v3/items/spec API Docs : https://developer.walmart.com/us-marketplace/reference/getspec

Example call body :

{
  "feedType": "MP_ITEM",
  "version": "5.0.20250121-19_24_23-api",
  "productTypes": [
    "Henna Stencils"

  ]
}

Mapping :

The response would be a JSON schema :

schema.json

The schema will then be used to validate against when creating new items on Walmart.

We have two types of attributes which apply for each category :

• Orderable - is what we can call the main section of the product including identifiers, prices, names, brands etc. This could be considered more general info about the product
• Visible - 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.

For every category we must have these Orderable attributes:

OR Product > MPN OR Product > UPC OR Product > ISBN | Here we can have ISBN, GTIN, UPC and EAN depends from which field we are picking we are sending the correct productId Type. The Priority is as follows: If we have EAN we push EAN if EAN is empty the second field is MPN is MPN is empty we push UPC and last one is ISBN for books only | | sku | Yes | Product > SKU | | | price | Yes | Listing > Price | | | msrp | No | Listing > RRP | | | ShippingWeight | Yes | Product > Weight | | | stateRestrictions>states | No | Listing Walmart > Applicable States ISO2 | | | stateRestrictions>stateRestrictionsText | No | Listing Walmart > Restriction Text | |

Apart from the Orderable attributes which applies for every category we have Visible attributes which are specific for each category. Lets take for example category - T-Shirts

"properties": [    
      "productName",
      "brand",
      "shortDescription",
      "keyFeatures",
      "mainImageUrl",
      "countPerPack",
      "count",
      "multipackQuantity",
      "isProp65WarningRequired",
      "ageGroup",
      "shirtNeckStyle",
      "clothingSize",
      "clothingSizeGroup",
      "clothingStyle",
      "clothingTopStyle",
      "color",
      "colorCategory",
      "condition",
      "fabricCareInstructions",
      "fabricContent",
      "gender",
      "has_written_warranty",
      "netContent",
      "sleeveLengthStyle",
      "smallPartsWarnings",
      "zippered",
      "academicInstitution",
      "productSecondaryImageURL",
      "assembledProductLength",
      "assembledProductHeight",
      "assembledProductWeight",
      "assembledProductWidth",
      "globalBrandLicense",
      "prop65WarningText",
      "character",
      "character_group",
      "fastenerType",
      "clothing_feature",
      "clothingFit",
      "clothing_occasion",
      "clothing_shoulder_style",
      "designer",
      "embellishmentType",
      "fabric_construction",
      "frameColorConfiguration",
      "frontEndPhotoPartner",
      "manufacturer",
      "manufacturerPartNumber",
      "maximumOrderQuantity",
      "minimumOrderQuantity",
      "modelNumber",
      "netContentStatement",
      "pieceCount",
      "photoPaperFinishConfiguration",
      "pattern",
      "personalRelationship",
      "photoAccessoryItemSku",
      "photoConfigurationAttributeNames",
      "photoItemStoreUpc",
      "photoOrderQuantityTier",
      "productLine",
      "recycledMaterialContent",
      "ib_retail_packaging",
      "sleeveStyle",
      "sportsLeague",
      "sportsTeam",
      "t_shirt_type",
      "theme",
      "thirdPartyAccreditationSymbolOnProductPackageCode",
      "warrantyText",
      "warrantyURL",
      "variantGroupId",
      "variantAttributeNames",
      "isPrimaryVariant",
      "swatchImages"
    ]

The payload is structured the way that in every category after the properties we have required node where we have a list of required attributes for that category:

"required": [
                                        "colorCategory",
                                        "color",
                                        "clothingTopStyle",
                                        "shirtNeckStyle",
                                        "has_written_warranty",
                                        "clothingSizeGroup",
                                        "shortDescription",
                                        "mainImageUrl",
                                        "clothingStyle",
                                        "countPerPack",
                                        "smallPartsWarnings",
                                        "brand",
                                        "productName",
                                        "multipackQuantity",
                                        "sleeveLengthStyle",
                                        "keyFeatures",
                                        "condition",
                                        "count",
                                        "fabricContent",
                                        "isProp65WarningRequired",
                                        "gender",
                                        "clothingSize",
                                        "zippered",
                                        "netContent",
                                        "fabricCareInstructions",
                                        "ageGroup"
                                    ]

If a specific attribute has required values they are available in each property as enum:

"colorCategory": {
                                            "$schema": "http://json-schema.org/draft-07/schema#",
                                            "type": "array",
                                            "title": "Color Category",
                                            "items": {
                                                "type": "string",
                                                "enum": [
                                                    "Blue",
                                                    "Brown",
                                                    "Gold",
                                                    "Gray",
                                                    "Purple",
                                                    "Clear",
                                                    "Yellow",
                                                    "Off-White",
                                                    "Multicolor",
                                                    "Black",
                                                    "Beige",
                                                    "Pink",
                                                    "Orange",
                                                    "Green",
                                                    "White",
                                                    "Red",
                                                    "Silver",
                                                    "Bronze"
                                                ]
                                            },
                                            "minItems": 1,
                                            "description": "Closed List - Select the color from a short list that best describes the general color(s) of the item. This improves searchability as it allows customers to view items by color from the left navigation when they perform a search.\n\nPlease list all colors for the item. If the item has more than one color, please select Multi-color in addition to primary colors. Don’t list more than the three main colors.",
                                            "examples": "",
                                            "comments": "@group=Required for the item to be visible on Walmart website"
                                        }

We should have some common root Visible attributes mapping :

Sub-Attribute Logic: If we have Attribute with Sub Attributes we will have it like “attribute>subattribute” and every other if any sub sub attribute will be added with additional “>” like “attribute>subattribute >subsubattribute”.

Category: For the Category we will be using a standard for navigation path {Category} > {productTypeGroupName} > {productTypeName} … In short ' > ' with spaces included will be separator for the labels of the category.

Attributes structure: title - Item Specific Name enum - Item Specific Value (if any otherwise free text)

Sub-Attributes Structure:

Walmart handles their sub-attributes in a complex multi-attribute context, so we need to have the following structure in Item Specifics name we always start with the primary attribute(with a number) then followed by the subattribute and value in the Item Specifics Value - attribute[number]>subattribute=value.

For example if we take heelHeight . It is considered a complex multi-attribute so should be input like

heelHeight[1] > measure = 30 heelHeight[1] > unit = in

More info on complex multi attributes can be found in the taxonomy abstraction - Taxonomy General requirements

Taxonomy export file

In order to generate the taxonomy file we will need to create a new record in Taxonomy export with: Marketplace = Walmart Status = pending Category for Export = Possible values are “all”, (we can also specify which exact categories) Email = email to which the file will be send

We want to have a logic and if the user has selected 5 or more categories for export, we want to export them in a single zip file. This will be valid also if all categories are being exported. More details on taxonomies can be found here - Taxonomy General requirements .

PrimaryCatName- will be the name of the final category (leaf) Category path - Will have the full path Is Leaf - Always yes Item Specifics - Will be the same and for the sub-attributes we will have to store them as we expect to be optimized like fabricContent[1]>materialPercentage fabricContent[1]>materialName Required - we get this from the required node Enumeration - we set it as Yes if any enumerations are available Values - we add all enumeration for the attribute separated by | (pipe). If we have sub-attributes we add all enums for the main attribute