The Multi Item Inventory API provides suppliers with near real-time visibility of available inventory at our Walmart stores. Suppliers can use this endpoint to request inventory status information, using either the GTIN or Walmart Item Number, for up to 100 items.

Endpoints

POST

/search-items

Request Body Details

Parameter	Description	Data Type
item_type	The query parameter used to uniquely identify the items. Please see Accepted Item Types below for the currently accepted item types.	String
store_nbr	This is an identifying number of a store within a country. It is the most used store identifier and is an essential store attribute for reporting.	Integer
item_type_values	An array containing either the 14-digit Global Trade Item Numbers (gtin) or the Walmart Item Numbers (wm_item_number) that uniquely identify the items. A maximum of 100 values can be passed.	Array

Accepted Item Types

Item Type	Description
gtin	The 14-digit Global Trade Item Number (GTIN) that uniquely identifies the items.
wm_item_number	The 9-digit Walmart Item Number that uniquely identifies the items.

Response Details

Parameter	Description	Data Type
supplier_name	The name of the supplier.	String
store_nbr	The store number(s) associated with the items.	Integer
items	The array that will contain the list of items identified and their inventory, by location and state.	Array
gtin	The 14-digit Global Trade Item Number that uniquely identifies the items.	String
wm_item_number	The Walmart Item Number that uniquely identifies the items.	String
inventory_locations	The array that will contain the details of the inventory by location.	Array
location_area	The location of the item.	String
state	The status of the inventory (ie, available).	String
quantity	The number of items that are currently available for sale at store level.	Double
cid_level_inventories	The array that will contain the details of the inventory aggregated at Consumer ID (CID) level.	Array
cid	The specific Consumer ID.	Integer
cross_references	The array that will contain the details of the inventory that is mapped to the CID.	Array
last_updated_time	Latest time when the data is updated. Timestamp is specified in ISO format “YYYY-MM-DDTHH24:MM:SS” in UTC timezone.	Date
data_retrieval_status	Indicates if the inventory retrieval was successful (i.e., Success, Error). Success responses will be followed by inventory information. Error responses will be followed by reasons. See Response Errors table below for additional information.	String
reason	The reason any data was not successfully retrieved for the corresponding item_type. Appears only in the case that data_retrieval_status is "ERROR".	String

Response Errors

Item-related response errors will appear in the response body. Find common response errors and samples below.

Scenario	Array Response Sample
wm_item_number not mapped to the supplier	{ "supplier_name": "Awesome Company", "store_nbr": 100, "items": [ { "wm_item_number": "297349", "data_retrieval_status": "ERROR", "reason": "WM_ITEM_NUMBER not mapped to the supplier" } ] }
gtin not mapped to the supplier	{ "supplier_name": "Awesome Company", "store_nbr": 100, "items": [ { "gtin": "00037000825617", "data_retrieval_status": "ERROR", "reason": "GTIN not mapped to the supplier" } ] }
No data found (gtin)	{ "supplier_name": "AWESOME COMPANY", "store_nbr": 1132, "items": [ { "gtin": "12312312312312", "data_retrieval_status": "ERROR", "reason": "No data found" } ] }
No data found (wm_item_number)	{ "supplier_name": "AWESOME COMPANY", "store_nbr": 1132, "items": [ { "wm_item_number": "123456", "data_retrieval_status": "ERROR", "reason": "No data found" } ] }

Error Codes

API call attempts have the potential to return a variety of errors. Find common error codes, reasons, and resolution details below.

400 (BAD REQUEST)

Scenario	Reason	Resolution	Response Sample
Invalid gtin	Can occur when the user provides an invalid GTIN in the request, such as: a. GTIN has special characters b. GTIN is a negative value c. GTIN contains anything other than a number d. GTIN is more than or less than 14 digits	Please provide a valid GTIN for the given store_nbr in the request header..	{ "type": "https://uri.walmart.com/errors/invalid-request", "title": "Request is not well-formed, syntactically incorrect, or violates schema.", "trace_id": "183847083bdbeb5a45b5ec4d40414b54", "errors": [ { "code": "https://uri.walmart.com/errors/invalid-property-value", "reason": "The value of the property is invalid.", "property": "/item_type_values[0]/-00629071000919", "location": "body" } ], "status": 400, "detail": "Invalid request parameters received", "instance": "/search-items" }
Invalid wm_item_number	Can occur when the user provides an invalid wm_item_number in the request, such as: a. wm_item_number has special characters b. wm_item_number is a negative value c. wm_item_number contains anything other than a number d. wm_item_number is more than or less than 14 digits	Please provide a valid wm_item_number for the given store_nbr in the request header.	{ "type": "https://uri.walmart.com/errors/invalid-request", "title": "Request is not well-formed, syntactically incorrect, or violates schema.", "trace_id": "18390cee541c0b5a5450baef135f5fdd", "errors": [ { "code": "https://uri.walmart.com/errors/invalid-property-value", "reason": "The value of the property is invalid.", "property": "/item_type_values[0]/-30588055", "location": "body" } ], "status": 400, "detail": "Invalid request parameters received", "instance": "/search-items" }
Invalid store_nbr	Can occur when the user provides an invalid store_nbr in the request, such as: a. store_nbr has length more than 6 b. store_nbr has length less than 2	Provide a valid store_nbr in the request header.	{ "type": "https://uri.walmart.com/errors/invalid-request", "title": "Request is not well-formed, syntactically incorrect, or violates schema.", "trace_id": "183846bb08805d5a2555ecb650fb23d2", "errors": [ { "code": "https://uri.walmart.com/errors/invalid-property-length", "reason": "The value of a property is too short or too long.", "property": "/store_nbr/-1132", "location": "body" } ], "status": 400, "detail": "Invalid request parameters received", "instance": "/search-items" }
Invalid item_type	Can occur when the user provides an invalid item_type in the request. Item type must be "gtin" or "wm_item_number."	Provide a valid item_type in the request header.	{ "type": "https://uri.walmart.com/errors/invalid-request", "title": "Request is not well-formed, syntactically incorrect, or violates schema.", "trace_id": "18390d2b6f64d25a9bb0904cdf72b036", "errors": [ { "code": "https://uri.walmart.com/errors/invalid-property-value", "reason": "The value of the property is invalid.", "property": "/item_type/this", "location": "body" } ], "status": 400, "detail": "Invalid request parameters received", "instance": "/search-items" }
Mandatory property is missing in request	Can occur when a mandatory property is missing, such as: store_nbr, item_type, item_type_values.	Provide all mandatory properties in the request.	{ "type": "https://uri.walmart.com/errors/invalid-request", "title": "Request is not well-formed, syntactically incorrect, or violates schema.", "trace_id": "183846d1d99dbe5a2e7b7bfd1cd4b500", "errors": [ { "code": "https://uri.walmart.com/errors/invalid-property-value", "reason": "The value of the property is invalid.", "property": "/store_nbr/", "location": "body" } ], "status": 400, "detail": "Invalid request parameters received", "instance": "/search-items" }

401 (UNAUTHORIZED)

Error Message	Reason	Resolution	Response Sample
Could not authenticate inrequest, Authorization token.	Can occur if the token was generated for some other consumer_id	Make sure you are using the correct client credentials. Please generate a new Bearer token.	{ "details": { "Description": "Holder consumer id : XXXXX in access token ******* does not match the sender consumer id : YYYYYY", "wm_svc.version": "1.0.0", "wm_svc.name": "inventory-status", "wm_svc.env": "xxx" } }
wm_consumer.id provided is not mapped in application database.	The request is valid but the consumer_id is not mapped in the application to server the request	Please provide a valid Consumer ID in the request or contact support.	{ "type": "https://uri.walmart.com/errors/authentication-failure", "title": "Authentication failed due to missing Authorization header, or invalid authentication credentials.", "trace_id": "183846423c54315a367dc59ca4f2a3bf", "status": 401, "detail": "WM_CONSUMER.ID is not found", "instance": "/search-items" }
Could not authenticate in request, Authorization token	Can occur if the token is expired.	Please generate a new Bearer token.	{ "details": { "Description": "Access token : ******* validation failed with error : expired token", "wm_svc.version": "1.0.0", "wm_svc.name": "inventory-status", "wm_svc.env": "xxx" } }
Could not authenticate in request, Authorization token	Occurs if mandatory "Authorization" key is missing in the header.	Please add "Authorization" key in header and provide valid token	{ "details": { "Description": "Required OAuth Access Token is missing", "wm_svc.version": "1.0.0", "wm_svc.name": "inventory-status", "wm_svc.env": "xxx" } }
Could not authenticate in request, Authorization token	This occurs if passed "Authorization" token is invalid.	Please generate a new Bearer token and pass it in the request.	{ "details": { "Description": "Exception occurred while validated token info for access token ******* : Http request failed with status code : 400 and reason : Bad Request", "wm_svc.version": "1.0.0", "wm_svc.name": "inventory-status", "wm_svc.env": "stg" } }

403 (FORBIDDEN)

Error Message	Reason	Resolution	Request Sample
Unsubscribed consumer_id	This occurs when provided Consumer ID is not subscribed and token generated for a valid Consumer ID.	Please correct the consumer_id	{ "details": { "Description": "The consumer id 0533d1dd-af1a-42c1-9638-3d682b065fe2 is not subscribed to the service name - inventory-events - 1.0.0 - stg", "wm_svc.version": "1.0.0", "wm_svc.name": "inventory-status", "wm_svc.env": "stg" } }
The Consumer ID is not provided to the service name.	When the "wm_consumer.id" header is not present in the request. Or “wm_consumer.id" is either null.	Please use the provided Consumer ID & pass in the request header.	{ "details": { "Description": "The consumer id null is not subscribed to the service name - inventory-events - 1.0.0 - xxx", "wm_svc.version": "1.0.0", "wm_svc.name": "inventory-status", "wm_svc.env": "xxx" } }

404 (NOT FOUND)

Error Message	Reason	Resolution	Response Sample
Requested resource does not exist	The provided URL is incorrect.	Please use the correct endpoints. Refer to individual endpoint reference pages.	{ "type": "https://uri.walmart.com/errors/resource-not-found", "title": "The specified resource does not exist.", "trace_id": "183932c36100395af18d76211492259a", "status": 404, "detail": "Requested resource does not exist", "instance": "/search-item" }

405 (METHOD NOT ALLOWED)

Error Message	Reason	Resolution
Method not allowed.	An incorrect HTTP verb has been used.	Use the correct request method. Refer to the endpoint reference pages or endpoint quick view page for relevant methods.

429 (TOO MANY REQUESTS)

Error Message	Reason	Resolution
Too many requests, please retry after some time.	This is possibly due to a number of requests exceeding the given quota. The peak rate limit for Near Real Time API is generally 600 transactions per minute (TPM). Please refer the Throttling section in the endpoint reference pages for specific endpoint information.	Since the requests are getting throttled, it is suggested to try again after some time.

500 (INTERNAL SERVER ERROR)

Error Message	Reason	Resolution
Internal server error.	One or more services are unavailable. Please contact support.	Please contact support.

Sandbox Test Values

Below are the sample Request Parameters (store_nbr & GTIN combinations) you can utilize to test the Multi Item endpoint for successful and error scenarios in your sandbox environment. The values provided are strictly applicable for the sandbox environment only and will only work with a sandbox consumer ID.

Response Code	Store Number	GTIN	Scenario	Response Sample
SUCCESS 200 OK	45	44444444444444- 44444444444449 55555555555555- 55555555555559	Successful	{ "supplier_name": "Awesome Company", "store_nbr": 45, "items": [ { "gtin": " 44444444444449", "wm_item_number": "444444449", "data_retrieval_status": "SUCCESS", "inventory_locations": [ { "location_area": "STORE", "state": "AVAILABLE", "quantity": "13.0" } }, { "location_area": "BACKROOM", "state": "NET_AVAILABLE", "quantity": "14.0" } ...
404 NOT FOUND	30 or 45	82233344455	GTIN not mapped to the supplier	{ "type": "https://uri.walmart.com/errors/resource-not-found", "title": "The specified resource does not exist.", "trace_id": "18393517ce713a5a2ffca84d8bedbc16", "status": 404, "detail": "No data found", "instance": "/search-items" }
	45	55555555555555	Invalid URL	{ "type": "https://uri.walmart.com/errors/resource-not-found", "title": "The specified resource does not exist.", "trace_id": "1839353418d7b95a136c944a2ff5d0ec", "status": 404, "detail": "Requested resource does not exist", "instance": "/search-item" }
400 BAD REQUEST	-45	44444444444444	Invalid store number	{ "type": "https://uri.walmart.com/errors/invalid-request", "title": "Request is not well-formed, syntactically incorrect, or violates schema.", "trace_id": "1839358e1c31f45a4f82218ad7cb5476", "errors": [ { "code": "https://uri.walmart.com/errors/invalid-property-length", "reason": "The value of a property is too short or too long.", "property": "/store_nbr/-45", "location": "body" } ], "status": 400, "detail": "Invalid request parameters received", "instance": "/search-items" }
	45	44444444444444	Invalid item_type	{ "type": "https://uri.walmart.com/errors/invalid-request", "title": "Request is not well-formed, syntactically incorrect, or violates schema.", "trace_id": "183935d31377265a24f4bf12237cd431", "errors": [ { "code": "https://uri.walmart.com/errors/invalid-property-value", "reason": "The value of the property is invalid.", "property": "/item_type/gtine", "location": "body" } ], "status": 400, "detail": "Invalid request parameters received", "instance": "/search-items" }
	45	- 44444444444444	Invalid GTIN or wm_item_number	{ "type": "https://uri.walmart.com/errors/invalid-request", "title": "Request is not well-formed, syntactically incorrect, or violates schema.", "trace_id": "1839359462335b5a0b1a24b81412828f", "errors": [ { "code": "https://uri.walmart.com/errors/invalid-property-value", "reason": "The value of the property is invalid.", "property": "/item_type_values[0]/-44444444444444", "location": "body" } ], "status": 400, "detail": "Invalid request parameters received", "instance": "/search-items" }

Disclaimer

Your use of the API documentation is at your own discretion and risk. To the maximum extent permitted by law, the APIs, documentation and all related software, components, and support are provided by Walmart on an "as-is" and "as available" basis without any warranties of any kind, and Walmart expressly disclaims any and all express and implied warranties, including, but not limited to, warranties of merchantability, fitness for a particular purpose, title, noninfringement, non-interference, and warranties arising from a course of dealing. You acknowledge that Walmart does not warrant that the APIs will be uninterrupted, timely, secure, or error-free. Walmart may modify and delete API documentation in its sole discretion and without notice.

In no event shall Walmart be liable to you or any third parties for any damages whatsoever, including, without limitation, those resulting from loss of use, damage to your computer system, loss of data or profits, or any liability arising out of or in connection with the use of the APIs, documentation, software, components, or support.