Guides
My Account

Get item setup requirements

The get spec API lets you view item setup requirements for a specific product type or a set of product types (up to 20 per request). Use it to identify required attributes, allowed values, formatting rules, and conditional requirements before you build item setup payloads.

Endpoint

POST https://marketplace.walmartapis.com/v3/items/spec

Request sample

curl --request POST \ --url https://marketplace.walmartapis.com/v3/items/spec \ --header 'WM_QOS.CORRELATION_ID: b3261d2d-028a-4ef7-8602-633c23200af6' \ --header 'WM_SEC.ACCESS_TOKEN: <ACCESS_TOKEN>' \ --header 'WM_SVC.NAME: Walmart Marketplace' \ --header 'accept: application/json' \ --header 'content-type: application/json' \ --data '{ "feedType": "MP_WFS_ITEM", "version": "5.0.20250121-19_24_23-api", "productTypes": ["Baby Blankets"] }'

Request body

Include the following fields in the request body to retrieve the spec:

  • feedType (string): Feed type of the item setup data model you want the spec for (example: MP_WFS_ITEM)
  • version (string): The spec version you want to retrieve (example: 5.0.20250121-19_24_23-api)
  • productTypes (string[], optional): One or more product types; limit 20 (example: Baby Blankets, Animal Food, Cell Phones)

Modify your code

  1. Retrieve spec for a single product type (recommended)

Limit response size and get the most relevant requirements by passing one product type:

{ "feedType": "MP_WFS_ITEM", "version": "5.0.20250121-19_24_23-api", "productTypes": ["Baby Blankets"]
}

  1. Retrieve spec for multiple product types (batch up to 20)

{ "feedType": "MP_WFS_ITEM", "version": "5.0.20250121-19_24_23-api", "productTypes": ["Baby Blankets", "Crib Blankets", "Wearable Baby Blankets"]
}

  1. Reduce retries by validating product types first

If you pass invalid product types for the given feedTypeversion, you may receive a 207 partial response (schema returned + errors) or a 400 invalid request. To avoid this:

  • confirm product types are valid for that spec version (often via taxonomy for the same version), and
  • keep version pinned in your integration so validations don’t drift.

  1. When you need the full schema

If you’re looking for all supported product types and attributes, a manual download of the full schema is often the fastest way to review what’s available. You can download it from the Item spec versioning and diff reporting page.

Response sample (200)

A successful response returns a schema object containing JSON Schema draft-07. The schema describes the shape of the item spec and includes required fields, enums, validation limits, and conditional requirements.

Example (excerpt):

{ "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "MPItemFeedHeader": { "type": "object", "properties": { "businessUnit": { "type": "string", "enum": ["WALMART_CA","WALMART_US","ASDA_GM"] }, "locale": { "type": "string", "enum": ["en"] }, "version": { "type": "string", "enum": ["5.0.20241118-04_39_24-api"] } }, "required": ["businessUnit","locale","version"] } } }
}

Response sample (207)

A 207 Partial response means Walmart returned a schema, but one or more inputs (commonly product types were invalid. The response includes schema plus an errors array.

Example:

{ "schema": { "...": "..." }, "errors": [ "Carrot is not a valid PT for MP_WFS_ITEM/5.0.20241118-04_39_24" ]
}

Result

After calling Get Spec successfully, you can:

  • Determine the required attributes for each product type (required)
  • Validate allowed values (enum) and formatting (format, such as uri)
  • Enforce quality constraints (minLength, maxLength, minItems, numeric limits)
  • Implement conditional validation using if / then rules (for example, warranty, Prop 65, hazmat/battery rules)

Common conditional patterns in the schema include:

  • If has_written_warranty is Yes - Warranty URL, then warrantyURL is required
  • If has_written_warranty is Yes - Warranty Text, then warrantyText is required
  • If isProp65WarningRequired is Yes, then prop65WarningText is required
  • If chemicalAerosolPesticide is Yes (or certain battery types apply), then safetyDataSheet may be required

Error handling

400 Bad Request

Returned when the request is invalid (for example, invalid productTypes for the requested feedType/version).

{ "code": "INVALID_REQUEST.GMP_ITEM_QUERY_API", "description": "Invalid product types in the request for MP_WFS_ITEM/5.0.20241118-04_39_24", "info": "Request invalid.", "severity": "ERROR", "category": "DATA", "field": "productTypes"
}

500 Invalid parameter / system error

Returned when the system encounters an error or mandatory request parameters are missing.

{ "code": "SYSTEM_ERROR.GMP_ITEM_QUERY_API", "description": "System encountered some internal error.", "info": "One or more mandatory request parameters are missing.", "severity": "ERROR", "category": "DATA", "field": "Name is null"
}

Next steps

  • If your spec response is large, use productTypes to fetch only what you need (up to 20 per call).
  • If you receive 207, remove/fix invalid product types and retry.
  • For a complete view of supported product types, download the full schema from the Item spec versioning and diff reporting page.