Guides
My Account

Utility APIs

Overview

The Utility APIs allow you to search for all Walmart item departments and all categories within a department, or retrieve the taxonomy of categories aligned to an item spec feed type and version. The Utilities APIs are helper endpoints that let you:

  • Retrieve Walmart.com taxonomy structures (departments, categories, and item-spec taxonomy)
  • Discover Walmart item departments and browse all categories within a department
  • Check Marketplace API platform status (operational vs degraded)

These endpoints are commonly used to validate item setup, drive category selection UX, support consistent item classification, and monitor integration health.

Market availability

These Utilities APIs are designed for the Walmart Marketplace ecosystem and available only in the US.

How it works

  1. Your system authenticates and sends required Walmart headers (access token, correlation ID, service name, etc.).

  2. You call taxonomy endpoints to fetch the structure you need:

    • Full taxonomy by item spec
    • Departments list
    • Categories for a department

  3. You cache results and refresh periodically (taxonomy changes are infrequent compared to item/price/inventory updates).

  4. You call API status when troubleshooting or building operational dashboards.

Common user journey

  1. Build or validate item categorization: Fetch departments → pick a department → fetch categories → map internal categories to Walmart taxonomy
  2. Support item spec–specific workflows: Retrieve taxonomy by item spec version and feed type to align category selection with the spec you’re publishing against
  3. Operate and monitor> Poll platform status endpoint to quickly see if issues are systemic

Use cases

  • Category picker UI in a seller portal or internal tooling
  • Automated mapping of internal category trees to Walmart department/category IDs
  • Validation checks before publishing items (ensuring category exists / is allowed)
  • Segment internal reporting or analysis by department/category (for example, grouping assortment or performance in your own systems)
  • Operational monitoring and incident triage using platform status

Benefits

  • Reduces categorization errors and rework
  • Improves item onboarding success rate
  • Makes taxonomy selection deterministic and repeatable
  • Enables consistent taxonomy-driven organization across setup, maintenance, and reporting workflows
  • Improves observability during outages or degraded performance

Reference guide

This guide explains how to use the Utilities APIs, providing practical examples and step-by-step instructions for retrieving taxonomy (departments, categories, and taxonomy by spec) and checking API platform status.

For full technical details, including endpoints, parameters, and brief descriptions, refer to the Utilities API reference guide.

Available set of APIs

  • GET /v3/utilities/taxonomy — Taxonomy by item spec (feedType + version) and related taxonomy datasets returned by the endpoint
  • GET /v3/utilities/taxonomy/departments — Search for all departments and department IDs (grouped under super departments)
  • GET /v3/utilities/taxonomy/departments/{departmentId} — search for all item categories within a department
  • GET /v3/utilities/apiStatus — API platform status by API group

Rate limits

If you submit too many feeds in a short period of time, you may exceed Walmart’s rate limits and receive HTTP 429 (Too Many Requests) responses. For more details on throttling and best practices, refer to the Rate Limiting Guide.

Next steps

Updated about 9 hours ago