Item Recommendations

This API provides a report of unadvertised items, from an advertiser’s full Walmart product catalog, that have been previously purchased and have the potential to perform well in advertising campaigns. Advertisers can use the report to identify items to add to new or in-flight campaigns, to help boost sales. The recommendations are sorted with most ordered items showing on the top of the report.

Note:

• Lookback window is 30 days
• The report provides up to 1000 items for a given advertiser
• With variant bidding launch, the Item Recommendations will also include variant items
• The item recommendations report is refreshed weekly on Thursday 12 pm PST

Description: You can place a request for item or keyword recommendations by providing advertiser ID, recommendation type and format

URL: ​POST/api/v1/snapshot/recommendations

Query Parameters

Parameter	Notes	Type	Required	Possible Values
auth_token	The token will provide you the access to the API. It is same for all advertisers you access through the API.	string	Y	Please utilize the generated auth_token shared with you at the time of partner onboarding from the Getting Started Guide
advertiserId	The id of advertiser	integer	Y	The advertiser Id for which the recommendation is to be retrieved
recommendationType	The type of the recommendation required	string	Y	Values of recommendation type: itemRecommendations, keywordRecommendations
format	Choose the format type for your snapshot	string	Y	Types of formats: gzip, zip Note: gzip allows decompression while file is being transferred over the network, hence it is a faster and simpler way to download the reports

Headers

Header Name	Description	Required	Values
WM_CONSUMER.ID	We will provide you the consumer ID to access the API. It is same for all advertisers you access through the API.	Y	Please 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_SIGNATURE	Auth signature as an API key	Y	Use the signature generator code from Getting Started Guide to generate this value
WM_CONSUMER.intimestamp	Timestamp for which the auth signature is generated. Use Unix epoch format for the timestamp	Y	Use the signature generator code (Getting Started Guide) to generate this value

Sample Request

curl -X POST \
"https://developer.api.stg.walmart.com/api-proxy/service/WPA/Api/v1/api/v1/snapshot/recommendations?auth_token=1234"  \
-H "WM_SEC.AUTH_SIGNATURE: ***********" \
-H "WM_CONSUMER.ID: adfwe-v23-faasd2r-afs-asdfqeff" \
-H "WM_CONSUMER.intimestamp: 1565309779"\
 -H "Content-Type: application/json" \
 -H "accept: application/json" \
-d "[
{"advertiserId" : "600001",
 "recommendationType": "itemRecommendations",
 "format": "gzip"}
  ]"

Response

Element	Description	Type
code	The response code can have following values:   success failure	string
details	Details of the error if value of response code is failure	string
snapshotId	ID of the snapshot	string
jobStatus	It is an indicator to confirm status of snapshot generation. The possible values of jobStatus are: pending, processing, done, failed, expired	string

Sample Response

[
  {
      "code": "success",
      "snapshotId": "15467655-92ef-490d-a2c8-0157990f57f8",
      "details": " ",
     " jobStatus ": "pending"
  }
]

Description: You can retrieve item recommendations and keyword recommendations snapshots by providing snapshot id and advertiser id for an advertiser.

Note:

• The output is generated in a “zip/gzip” file depending upon format chosen
• The file type enclosed in zip is CSV. You can request the following type of snapshots:
  • Item Recommendations
  • Keyword Recommendations

URL: GET/api/v1/snapshot

Query Parameters

Parameter	Description	Type	Required	Possible Values
auth_token	The token will provide you the access to the API. It is same for all advertisers you access through the API.	string	Y	Please utilize the generated auth_token shared with you at the time of partner onboarding from the Getting Started Guide
advertiserId	The ID of the advertiser	integer	Y	Unique numeric identifier
snapshotId	The ID of the snapshot	string	Y	Unique alpha numeric identifier

Sample Request 1

curl -X GET\
"https://developer.api.stg.walmart.com/api-proxy/service/WPA/Api/v1/api/v1/snapshot?advertiserId=600001&snapshotId=15467655-92ef-490d-a2c8-0157990f57f8 &auth_token=1234"  \
 -H "accept: application/json" \
-H "WM_SEC.AUTH_SIGNATURE: ***********" \
-H "WM_CONSUMER.ID: adfwe-v23-faasd2r-afs-asdfqeff" \
-H "WM_CONSUMER.intimestamp: 1565309779" \

Sample Request 2

curl -X GET\
"https://developer.api.stg.walmart.com/api-proxy/service/WPA/Api/v1/api/v1/snapshot?advertiserId=600002&snapshotId=09815467655-92ef-490d-a2c8-0157990f57f867&auth_token=1234"  \
 -H "accept: application/json" \
-H "WM_SEC.AUTH_SIGNATURE: ***********" \
-H "WM_CONSUMER.ID: adfwe-v23-faasd2r-afs-asdfqeff" \
-H "WM_CONSUMER.intimestamp: 1565309779" \

Response

Element	Description	Type
snapshotId	Id of the snapshot to be retrieved	string
jobStatus	It is an indicator to confirm status of snapshot generation. The possible values of jobStatus are: pendingprocessingdonefailedexpired	string
details	provides download URL when processed (once jobStatus reaches to state “done”)	string
code	The response code can have following values:   success, failure	string

Sample Response – Item Recommendations Snapshot

[
  {
      "code"        : "success",
      "snapshotId": "15467655-92ef-490d-a2c8-0157990f57f8",
      "details"       : "https://advertising.walmart.com/qa/file/15467655-92ef-490d-a2c8-0157990f57f8 ",
      " jobStatus ": "done"
  }
]

The snapshot file is zipped CSV file format.

The response would be captured in one zip/gzip file as requested.

Example of the content of snapshot with id “15467655-92ef-490d-a2c8-0157990f57f8”. The file format is “CSV”:

reportDate,   itemId,   itemName,    suggestedBid,   brandName,    superDepartName,     departmentName,  category,      
 subCategory

2022-05-15,      1,        TestItem1,           1,                  Brand1,        SuperDepartment1,       Department1,        Category1,   
SubCategory1 
2022-05-15,      2,       TestItem2,           2,                   Brand2,         SuperDepartment2,      Department2,      Category2,                    
 SubCategory2 
2022-05-15,      3,       TestItem3,           3,                   Brand3,         SuperDpartmnt3,           Departmnt3,        Category3, 
SubCategory3

Columns	Description	Type
reportDate	The date when the report was generated	date
itemId	Unique identifier for the Item *With variant bidding launch, the item recommendations will also include variant items.	string
itemName	Item name for the given item Id	string
suggestedBid	Bid suggestion to bid in auto- campaign. *With enhancements to suggested bid, the bids for an item will be at product type level.	double
brandName	Brand name for the item	string
superDepartmentName	Group of Departments with similar family of items. Depending upon the Site Taxonomy, this can be blank.	string
departmentName	Group of Departments with similar family of items. Depending upon the Site Taxonomy, this can be blank.	string
category	Group of Sub-categories with similar family of items. Depending upon the Site Taxonomy, this can be blank.	string
subCategory	Group of items that meet similar needs. Depending upon the Site Taxonomy, this can be blank.	string

Q. Is it possible to have no item recommendations for a given advertiser? 

A. Yes, it is possible. It means that the seller/supplier currently does not have any unadvertised items that qualify for recommendations. Since recommendations are refreshed weekly, keep checking this API on a weekly basis. 

Q. I have added a recommended item to a campaign, but I am still seeing it in the report. 

A. The item that you added to your campaign from the Item recommendation tool will only be removed from the recommendations in the next weekly refresh.

Q. How far is the lookback window for unadvertised items? 

A. The lookback window for unadvertised items is 30 days.

Q. How often are the item recommendations refreshed? 

A. This report will be refreshed on a weekly basis.

Q. How are the recommendations sorted? 

A. The most ordered items show at the top of the report. 

Q. Does the Item Recommendations report include variant items? 

A. With variant bidding launch, the Item Recommendations report will also include variant items.

There is a rate limit in place on the allowed number of API operations per hour.

Operations per hour are computed as the sum of number of changes requested across all API requests during the hour.

For example, 5 keyword bid changes, creation of an ad group, adding an item, and a snapshot report request in any given hour, would be counted as 8 operations.

You will receive an HTTP 429 status error code and an error message about rule enforced in case of breaking ops limit.

To learn more about current applicable limits specific to your integration, please reach out to the API Partner Enablement team.