Guides
My Account

Get item taxonomy by spec

Call the Taxonomy API to retrieve Walmart taxonomy aligned to an item spec feed type and version. Use the returned hierarchy, names, and IDs to decide where to place products during item setup and maintenance.

This endpoint can return taxonomy in two response variants:

  • Product type taxonomy (PT): category → product type group → product type (with department mappings)
  • Category/subcategory taxonomy: category → subcategory (with subCategoryId values)

Endpoint

GET /v3/utilities/taxonomy

Request sample

curl -X GET \ "https://marketplace.walmartapis.com/v3/utilities/taxonomy" \ -H "WM_QOS.CORRELATION_ID: b3261d2d-028a-4ef7-8602-633c23200af6" \ -H "WM_SEC.ACCESS_TOKEN: eyJraWQiOiIzZjVhYTFmNS1hYWE5LTQzM....." \ -H "WM_SVC.NAME: Walmart Service Name" \ -H "accept: application/json"

Modify your code

  • Use a unique WM_QOS.CORRELATION_ID for each request.

  • Replace WM_SEC.ACCESS_TOKEN with your valid access token obtained through authentication

  • Target the item spec you’re using by passing feedType and version (Allowed values: item, MP_ITEM, MP_WFS_ITEM, MP_MAINTENANCE; and 3.2, 4.0, 4.1, 4.2).

    • feedType=MP_ITEM&version=4.2
    • feedType=MP_WFS_ITEM&version=4.1
    • feedType=MP_MAINTENANCE&version=4.1

  • If you omit feedType, expect the endpoint to return Item Spec v3.2 categories by default.

  • Use the right variant for your workflow

    • Use PT when you need product-type-driven selection and definitions.
    • Use Category/subcategory when you need stable IDs for category mapping.

  • Cache the response and refresh periodically instead of calling on every UI load.

  • Generate a new WM_QOS.CORRELATION_ID for each request when troubleshooting.

Response sample

Variant 1: Product type (PT) taxonomy

{ "itemTaxonomy": [ { "category": "Beauty", "description": "Beauty", "productTypeGroup": [ { "productTypeGroupName": "Fragrances", "description": "Fragrance", "productType": [ { "productTypeName": "Body Sprays", "description": "Body spray is a perfume or cologne product, similar to aerosol deodorant, which is intended to be used elsewhere on the body besides the armpits. Body sprays are lighter in strength than cologne, generally less expensive, and double as deodorant a body spray is just a milder form of perfume. Body spray is a mixture of water and alcohol along with various extracts. Body Sprays will also often be called Body Mists or Hair Mists. The Body Sprays product type includes Body Spray bundles, multi sets, and gift sets, as long as they don't contain perfume or cologne." } ], "department": [ { "departmentName": "BEAUTY", "departmentNumber": "46" } ] }, { "productTypeGroupName": "Skin Care", "description": "Skin Care", "productType": [ { "productTypeName": "Acne Creams", "description": "Acne products usually contain the active ingredient salicylic acid or benzoyl peroxide. These substances reduce the amount of oil your body produces. They also fight inflammation. These effects help treat existing blemishes and prevent new ones from forming. This includes acne cream, spot treatment, pads and patches." } ], "department": [ { "departmentName": "BEAUTY", "departmentNumber": "46" }, { "departmentName": "IMPULSE MERCHANDISE", "departmentNumber": "82" } ] } ] }, { "category": "Food", "description": "Food", "productTypeGroup": [ { "productTypeGroupName": "Baking & Cooking", "description": "Baking & Cooking", "productType": [ { "productTypeName": "Flours & Meals", "description": "This product type includes flour, meal, and other similar products used in baking and cooking." } ], "department": [ { "departmentName": "FOOD", "departmentNumber": "95" } ] } ] } ], "status": "SUCCESS"
}

Variant 2: Category/subcategory taxonomy

{ "status": "SUCCESS", "payload": [ { "category": "Animal", "subcategory": [ { "subCategoryName": "Animal Accessories", "subCategoryId": "559c5d924fff3d64de18bf45" }, { "subCategoryName": "Animal Food", "subCategoryId": "559c5d8f4fff3d64de18bf3d" }, { "subCategoryName": "Animal Health & Grooming", "subCategoryId": "559c5d90ed25b136f13a05df" }, { "subCategoryName": "Animal Other", "subCategoryId": "56f2eb66208f9a06158f1748" } ] }, { "category": "Art & Craft", "subcategory": [ { "subCategoryName": "Art & Craft", "subCategoryId": "571fdff7208f9a0cdb760a7f" } ] } ]
}

Result

  • With feedType and version, you can retrieve the taxonomy aligned to the item spec you’re publishing against.
  • Use taxonomy IDs to place products into the most appropriate category/subcategory and to group similar products consistently under the same taxonomy nodes.

Next steps

  • Use All departments and All categories if you want department-scoped category lists.
  • Use the returned category identifiers in your item workflows where taxonomy IDs are required.
  • If you need details about the latest individual item specs, refer to the Item spec versions guidance.

Updated about 15 hours ago