Guides

List Items

Retrieve list of items in the advertiser's catalog

📘

URL: POST/api/v1/items/list

Request Parameters

ParametersNotesTypeRequiredPossible Values
advertiserIdID of advertiser integerYUnique numeric identifier
isRestrictedSpecifies whether to retrieve the list of items in own catalog or from all available items.

Note:
  • filters for brand, category and subCategory are not supported when isRestricted = false
  • Default value of isRestricted is true
  • filter[itemName] is mandatory if isRestricted = false
BooleanNValues:
  • true
  • false
filter[itemId]List of item IDs for which details are to be retrieved.ArrayNValid item IDs
filter[itemName]Name of the item for which details are to be retrieved.

Note:
  • filter[itemName]
    is mandatory if isRestricted = false
  • Supports 'exact' match
List of
string		NValid item names
filter[catalog]Specify to fetch list of items from online or store or universal catalog.stringNEnum Values:
  • online: items sold online
  • stores:items sold in stores
  • universal: items sold both online and in stores
filter[gtin]GTIN of the item for which item details are to be retrieved.

Note: Supports 'exact' match		ArrayN
filter[department]Specify to fetch list of items in the designated department

Note:
  • This parameter is case insensitive
  • Supports 'exact' match
ArrayNValid department
filter[category]Specify to fetch list of items in the designated category

Note:
  • This parameter is case insensitive
  • Supports 'exact' match
ArrayThis field is required only if it is not set at ad group levelValid category
filter[subCategory]Specify to fetch list of items in the designated sub-category

Note:
  • This parameter is case insensitive
  • Supports 'exact' match
ArrayThis field is required only if:
-It is not
set at ad group level

-budgetType is set to be daily		Valid subcategory
filter[brandName]Specify to fetch list of items in the designated brand

Note:
  • Supports 'exact' match
ArrayNValid brand name
filter[itemType]Specify to fetch list of items of the specified type.
Note:

  • If filter[itemType]=BASE, only base items will be returned.
  • If filter[itemType]=VARIANT, only variant items will be returned.
  • If omitted, both types will be included.
StringNbase, variant
expandVariantsControls whether to expand results to include related variants when filtering by itemId or gtin.
  • Applies only with: filter[itemId] or filter[gtin].
  • Default: false.
When expandVariants = false (default):
  • Response includes only the items that directly match the filters.
When expandVariants = true:
  • If filter matches a base item:
    • Returns the base item and all its variants.
  • If filter matches a variant item:
    • Returns:
      1. the base item of the variant.
      2. The variant item itself.
      3. All other variants under the same base item.
BooleanNtrue, false
startIndexUse this parameter to fetch specific number of items from a list, in combination with count.

This indicates the starting position of the list

Note: Value of startIndex must be greater than and equal to 0. The default value is 0_		integerNInteger value

Example: To return the first ten catalog items, set startIndex=0 and count=10
countDefines the total number of items to be returned.
You can use this parameter in combination with startIndex, to fetch specific number of items from a list.

Note: Value of count must be greater than 0. The default value is 100		integerNInteger value

Example: To return the first ten catalog items, set startIndex=0 and count=1

Note:
"The error message TOO_MANY_FILTERS_PROVIDED_IN_REQUEST is returned when too many filters are used and the request is not processed "

👉

Rules/Validations

  • brand, category, and subCategory filters are not supported when isRestricted = false.
  • When isRestricted = false, the filter[itemName] field is mandatory.
  • Filters for itemName, gtin, department, category, subCategory, and brandName only support exact matches.
  • Filters for department, category, and subCategory are case-insensitive.
  • expandVariants can only be used with filter[itemId] or filter[gtin]. If expandVariants is provided without either of these filters, the API will return 400 Bad Request.


Headers

Header NameDescriptionRequiredValues
AuthorizationThe token will provide you the access to the API. It is same for all advertisers you access through the APIYPlease utilize the generated auth_token shared with you at the time of partner onboarding from the Getting Started Guide. This key can be repurposed for SP API access as well.
WM_CONSUMER.IDWe will provide you the consumer ID to access the API. It is same for all advertisers you access through the API.YPlease use the generated ConsumerId shared with you at the time of partner onboarding. Refer to the Getting Started Guide for further explanation on this
WM_SEC.AUTH_SIGNATUREAuth signature as an API keyYUse the signature generator code from Getting Started Guide to generate this value
WM_CONSUMER.intimestampTimestamp for which the auth signature is generated. Use Unix epoch format for the timestampYUse the signature generator code (Getting Started Guide) to generate this value
WM_SEC.KEY_VERSIONWe will provide you with the KEY VERSION to access the API. It is same for all advertisers you access through the APIY1

Sample Request - List Items API using multiple filters


curl -X POST \
'https://developer.api.us.stg.walmart.com/api-proxy/service/display/api/v1/api/v1/items/list' \ --header 'Content-Type: application/json' \
--header 'Authorization: Bearer <auth_token>'
--header 'WM_SEC.AUTH_SIGNATURE: **************' \
--header 'WM_SEC.KEY_VERSION: 1' \
 --header 'WM_CONSUMER.ID: adfwe-v23-faasd2r-afs-asdfqeff' \
--header 'WM_CONSUMER.intimestamp: 1565309779' --data '{ "advertiserId": 1, "isRestricted": true, "filter[itemId]": [29799], "filter[itemName]": ["Planner Datebook"], "filter[catalog]": "online", "filter[gtin]": ["0062"], "filter[department]": ["Office"], "filter[category]": ["Calendars"], "filter[subCategory]": ["Planners"], "filter[brandName]": ["brand"], "startIndex": 0, "count": 5 }'

Sample Request - List Items API using expandVariants

curl -X POST \
'https://developer.api.us.stg.walmart.com/api-proxy/service/display/api/v1/api/v1/items/list' \ --header 'Content-Type: application/json' \
--header 'Authorization: Bearer <auth_token>'
--header 'WM_SEC.AUTH_SIGNATURE: **************' \
--header 'WM_SEC.KEY_VERSION: 1' \
 --header 'WM_CONSUMER.ID: adfwe-v23-faasd2r-afs-asdfqeff' \
--header 'WM_CONSUMER.intimestamp: 1565309779' --data '{ "advertiserId": 1, "filter[itemId]": [29799], "expandVariants": true "startIndex": 0, "count": 5 }'

Sample Request - List Items API using expandVariants along with any other filter apart from item id and gtin.

curl -X POST \
'https://developer.api.us.stg.walmart.com/api-proxy/service/display/api/v1/api/v1/items/list' \ --header 'Content-Type: application/json' \
--header 'Authorization: Bearer <auth_token>'
--header 'WM_SEC.AUTH_SIGNATURE: **************' \
--header 'WM_SEC.KEY_VERSION: 1' \
 --header 'WM_CONSUMER.ID: adfwe-v23-faasd2r-afs-asdfqeff' \
--header 'WM_CONSUMER.intimestamp: 1565309779' --data '{ "advertiserId": 1, "filter[itemName]": [test], "expandVariants": true "startIndex": 0, "count": 5 }'

Sample Request - Brand Name Filter when isRestricted is false

curl -X POST \
'https://developer.api.us.stg.walmart.com/api-proxy/service/display/api/v1/api/v1/items/list' \ --header 'Content-Type: application/json' \
--header 'Authorization: Bearer <auth_token>'
--header 'WM_SEC.AUTH_SIGNATURE: **************' \
--header 'WM_SEC.KEY_VERSION: 1' \
 --header 'WM_CONSUMER.ID: adfwe-v23-faasd2r-afs-asdfqeff' \
--header 'WM_CONSUMER.intimestamp: 1565309779' --data '{ "advertiserId": 1, "filter[brandName]": ["test"], "isRestricted": false "startIndex": 0, "count": 5 }'

Response

ElementDescriptionType
codeThe response code can have following values:
• success
• failure		string
detailsDetails will populate an error message in case of code=failurestring
totalResultsTotal number of rows returned in the responseinteger
datadata will populate details of items, retrieved through request if code is success
  • catalog:Type of catalog of the returned item indicates whether the item is sold online, in-store, or through both channels
    • ONLINE - items sold online
    • STORE - items sold in store
    • UNIVERSAL - items sold both online and in store. For using these items in itemsets, use the item's GTIN in the itemset create/update calls
  • itemId: Id of the returned item
  • gtin: gtin of the returned item
  • itemName: Name of the returned item
  • imageUrl: URL of item image
  • itemPageUrl: URL of item page
  • brandName: brand to which the item belongs
  • department: Department under which the item is classified
  • category: category under which the item is classified
  • subCategory: subcategory under which the item is classified
  • baseItemId: Identifier of the item's base item
    • For a VARIANT item: the ID of its base item
    • For a BASE item: same as its own itemId
    • For a REGULAR item: the ID will be -1

Sample Response Success - List Items API using multiple filters


{ "code": "success", "totalResults": 1, "data": [ { "catalog": "ONLINE", "itemId": 29799, "gtin": "0062", "itemName": "Planner Datebook", "imageUrl": "imageUrl", "itemPageUrl": "itemPageUrl", "brandName": "brand", "department": "Office", "category": "Calendars", "subCategory": "Planners" "baseItemId" 1 } ]
}

Note: Please use 'GTIN' as the "itemType" in the call POST api/v1/itemset (hybrid expression), if the type of catalog is "UNIVERSAL"_

Sample Response Failure - List Items API using multiple filters


{ "code": "failure", "details": ["string"]
}

Sample Response Success - List Items API using expandVariants


{ "code": "success", "totalResults": 2, "data": [ { "catalog": "ONLINE", "itemId": 29799, "gtin": "1", "itemName": "itemName", "imageUrl": "imageUrl", "itemPageUrl": "itemPageUrl", "brandName": "brand", "department": "department", "category": "Personal Organizers", "subCategory": "Planners & Appointment Books", "baseItemId": 29799 }, { "catalog": "ONLINE", "itemId": 29790, "gtin": "1", "itemName": "itemName", "imageUrl": "imageUrl", "itemPageUrl": "itemPageUrl", "brandName": "brand", "department": "department", "category": "Personal Organizers", "subCategory": "Planners & Appointment Books", "baseItemId": 29799 } ]
}

Sample Response Failure - List Items API using expandVariants


{ "code": "failure", "details": ["string"]
}

Sample Response Failure - List Items API using expandVariants along with any other filter apart from item id and gtin.


{ "code": "failure", "details": ["INVALID_EXPAND_VARIANTS_FILTER_COMBINATION"]
}

Sample Response Failure - Brand Name Filter when isRestricted is false

{ "code": "failure", "details": ["BRAND_NAME_FILTER_NOT_PERMITTED_WHEN_IS_RESTRICTED_IS_SET_TO_FALSE"]
}

Updated 20 days ago