Snapshot Reports v1

Advertising Partners /

Overview

Use the snapshot API to generate and retrieve file-based snapshots of all the performance reports by entity, for a given advertiser, asynchronously.

Processing time range for a snapshot request is 10-15 mins.

Create Report Snapshot

Description: You can request a snapshot file for all performance reporting data available (until the date before current date) for a given advertiser using this method.

URL: POST/api/v1/snapshot/report

Query Parameters

Parameter Description Type Required Possible Values
advertiserId   The ID of the advertiser     integer Y Unique numeric identifier
startDate The first day to be considered in the performance report snapshot. It cannot be the current date date Y Date should be in format: yyyy-MM-dd

Note: This parameter is not applicable for Item Health report and the value will be ignored, however it is still required in the request  
endDate The last day to be considered in the performance report snapshot. It cannot be the current date.

Note: If report data is not available for the requested end date, the request will fail, and the response will contain endDate until which the performance report is available		date Y Date should be in format: yyyy-MM-dd

Note: This parameter is not applicable for Item Health report and the value will be ignored, however it is still required in the request
attributionWindow Window for click attribution.

*Window for view attribution is 1 day by default.		string      Y Allowed Values:
1) days3: Report will include 3-day attribution columns If a user selects this value.
2) days30: Report will include 30-day attribution columns if a user selects this value.
3) days14: Report will include 14-day attribution columns if a user selects this value.
4) allWith14: Report will include 3, 14, and 30-day attribution columns if a user selects this value
5) all: Report will include 3 and 30-day attribution columns If a user selects this value. Report will NOT include 14-day attribution columns if a user selects this value

Note: 14-day attribution data will only be available for period beyond 11/25/2019. Prior to this date, the value returned will be ‘0’. This parameter is not applicable for Item Health report and the value will be ignored. However, it is still required in the request    
reportType Type of report to be retrieved string Y Types of Report: keyword, adItem, platform, pageType, adGroup, brand, category, itemKeyword, itemHealth, itemHealthV2, placement    
extraFields   extraFields holds following parameters: date, splitAttribution   string N Get report snapshot aggregated at day level if you need a report by day

Note: Report by day can only be pulled for a maximum period of two months or 61 days. An error message will be returned if report is requested for more than the length of this time period. This parameter is not applicable for Item Health report and the value will be ignored; however, it is still required in the requests

splitAttribution: Use this parameter to get revenue break up by a) P&D (Pickup and Delivery) or 
b) Walmart.com along with other metrics

Note: With splitAttribution, you receive report snapshot aggregated by day, by default. So, use of date is not required
format Choose the format type for your snapshot string N Types of Format: 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. You will receive snapshot in zip format if no specific format is specified  

Note:

  • Response will be by default aggregated by the entire period requested. So, to get the report by day, please include the extraFields parameter with the value “date” in the request for all the report types except itemHealth and itemHealthV2 reports.
  • Request by “date”(extra field), start/end dates, and attributionWindow parameters are not applicable for Item Health report. The values provided will be ignored when requesting itemHealth and itemHealthV2 snapshot reports. However, these parameters are still required for all snapshot report generation.
  • To get report by campaigns, request report for adgroups and use the campaign ids returned in the report to aggregate the report.

Definition of Retrievable Reports

  • keyword: The performance of keywords you’re bidding on (available in Manual/Keyword bidding campaigns only). Data will only be included in the Keyword Performance report if at least one of the following is true:
    • Impressions are greater than 10
    • Ad spend is greater than $0.00
    • Attributed sales is greater than $0.00. 
  • adItem: The performance of ad items chosen in the ad groups in your campaign
  • platform: The performance of which device type the products in your campaign are displaying on
    • app – performance from the Walmart iOS and Android app
    • desktop – performance from the Walmart.com website on desktop and tablets
    • mobile – performance from the Walmart.com website on mobile web
    • others – performance from a platform we are unable to detect at the time 
  • pageType: The performance of those page types where the items in your campaign are showing on. E.g. Search Page, Browse Page, Item Page, Category page. 
    • browse – sub-category pages with algorithmic item selection (e.g. selecting the “Monitors” category in the “Electronics & Office” department) 
    • item – specific item pages 
    • search – search pages based on a customer’s query (e.g. searching “bed sets”) 
    • topic – custom curated search pages, found from searches outside of Walmart.com(such as search engines) that lead back to Walmart.com
    • category – category pages (e.g. selecting the “Feeding” category in the “Baby” department)
    • homepage – home page high visibility personalization carousels
      Note: This pageType report is only available for Auto Campaigns
    • other – any other pages not falling into the categories above or if our beacon was unable to track which page type the user was visiting
  • adGroup: The performance of individual ad groups within your campaign
  • brand: The Performance of the different brands within your campaign (available to Walmart suppliers only).
  • category: The performance of the categories of the items in your campaign (available to Walmart Suppliers only).
  • itemKeyword: The performance of individual items within your campaign, across searched Keywords for manual & auto bidding campaigns on Ingrid placements.
  • itemHealth: The performance of SKUs (items) that are part of the live ad campaigns. It enables advertisers to assess item health to select good SKUs from catalogue and improve campaign performance as a result. 
  • itemHealthV2: The performance of SKUs (items) that are part of the live ad campaigns. It enables advertisers to assess item health to select good SKUs from catalogue and improve campaign performance as a result. It is a new version of report type itemHealth under Snapshot Reports v1. With variant bidding launch, itemHealthV2 report will also include variant items. This new version includes primary variant id for a given item.
  • Few important points about itemhealth and itemHealthV2 reports are:
    • This report is available for both auto and manual campaigns
    • Only those items will be returned in the report which have been part of at least one active auto/manual campaign in ‘live’ status for at least 3 days.
    • The campaignIds and adGroupIds included in report response will only be for:
    • Campaigns that are live
    • Ad groups that are enabled for the date the report was generated
    • Request by “date”(extra field), start/end dates, and attributionWindow parameters are not applicable for Item Health report. The values provided will be ignored when requesting itemHealth snapshot report. However, these parameters are still required for all snapshot report generation. 
    • To know about health of cold start SKUs, users can create auto/manual campaign with SKUs they are interested in knowing health of.
    • You can find the item health report contents below
    • Look at recommended actions to improve the item health
  • Placement: The performance report for placements:
    • For a keyword campaign: Search In-grid, Carousel, Buybox, Others
    • For an Auto campaign: Search In-grid, Carousel, Buybox, Browse In-Grid, Stock Up, Home Page, Others

Note: For Auto campaigns, “carousel” in placement report includes aggregate performance across all ad carousels. For Manual campaigns, however, “carousel” includes “Item Page Carousel” and “Search Carousel”. These metrics are based on what placement is included as part of the campaign.

Note: Keyword Performance and Item Keyword reports both include data only if at least one of the following is true:

  • impressions are greater than 10
  • Ad spend is greater than $0.00
  • Attributed sale is greater than $0.00

Because of this you should expect a discrepancy between keyword reports and other reports so metrics should not be compared directly.  

Sample Requests for Create Snapshot 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 1

curl -X POST \ 
"https://developer.api.stg.walmart.com/api-proxy/service/WPA/Api/v1/api/v1/snapshot/report?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"\
 -d "[ 
           { 
    "advertiserId": 600001,
    "startDate": "2019-02-01",
    "endDate": "2019-03-01",
    "attributionWindow": "days3",
     "reportType": "keyword",
     "extraFields": ["date"],
     "format": "gzip"
     }
]"

Sample Request 2

curl -X POST \ 
"https://developer.api.stg.walmart.com/api-proxy/service/WPA/Api/v1/api/v1/snapshot/report?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"\
 -d "[
          { 
    "advertiserId": 600001,
    "startDate": "2030-02-01",
    "endDate": "2020-03-01",
    "attributionWindow": "days3",
     "reportType": "pageType"
       } 
  ]"

Sample Request 3

curl -X POST \ 
"https://developer.api.stg.walmart.com/api-proxy/service/WPA/Api/v1/api/v1/snapshot/report?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"\
 -d " [
             { 
    "advertiserId" : 600001,
    "startDate": "2019-02-01",
    "endDate": "2019-03-01",
    "attributionWindow": "days3",
     "reportType": "adGroup",
     "extraFields": ["date"],
      "format": "gzip"
      }

Sample Request 4

curl -X POST \ 
"https://developer.api.stg.walmart.com/api-proxy/service/WPA/Api/v1/api/v1/snapshot/report?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"\
 -d "[
         { 
    "advertiserId": 600001,
    "startDate": "2019-02-10",
    "endDate": "2019-02-14",
    "attributionWindow": "all",
     "reportType": "itemKeyword",
      "format": "zip"
        }
   ] "

Sample Request 5

curl -X POST \ 
"https://developer.api.stg.walmart.com/api-proxy/service/WPA/Api/v1/api/v1/snapshot/report?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"\
 -d "[
          { 
    "advertiserId": 600001,
    "startDate": "2019-02-01",
    "endDate": "2019-03-01",
    "attributionWindow": "days3",
     "format": "zip",
     "reportType": "itemHealth"
      } 
 ]"

Sample Request 6

curl -X POST \ 
"https://developer.api.stg.walmart.com/api-proxy/service/WPA/Api/v1/api/v1/snapshot/report?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"\
 -d "[
          { 
    "advertiserId": 600001,
    "startDate": "2019-02-01",
    "endDate": "2019-03-01",
    "attributionWindow": "days3",
     "format": "zip",
     "reportType": "itemHealthV2"
      } 
 ]"

Sample Request 7

curl -X POST \ 
"https://developer.api.stg.walmart.com/api-proxy/service/WPA/Api/v1/api/v1/snapshot/report?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"\
 -d "[
          { 
    "advertiserId": 600001,
    "startDate": "2019-02-01",
    "endDate": "2019-03-01",
    "attributionWindow": "days14",
     "reportType": "keyword"
         } 
   ]"

Sample Request 8

curl -X POST \ 
"https://developer.api.stg.walmart.com/api-proxy/service/WPA/Api/v1/api/v1/snapshot/report?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"\
 -d "[
         { 
    "advertiserId": 600001,
    "startDate": "2019-02-10",
    "endDate": "2019-02-14",
    "attributionWindow": "allWith14",
    "extraFields": ["splitAttribution"],
     "reportType": "adItem"
        }
    ]"

Sample Request 9

curl -X POST \ 
"https://developer.api.stg.walmart.com/api-proxy/service/WPA/Api/v1/api/v1/snapshot/report?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"\
 -d "[
         { 
    "advertiserId": 600001,
    "startDate": "2019-02-10",
    "endDate": "2019-02-14",
    "attributionWindow": "all",
     "reportType": "placement",
     "format": "gzip"
        }

Sample Request 10

curl -X POST \ 
"https://developer.api.stg.walmart.com/api-proxy/service/WPA/Api/v1/api/v1/snapshot/report?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"\
 -d "[
         { 
    "advertiserId": 600001,
    "startDate": "2019-02-10",
    "endDate": "2019-02-14",
    "attributionWindow": "allWith14",
     "reportType": "placement",
     "format": "gzip"
        }
    ]"

Sample Resonses for Create Snapshot Requests

Response

Element  Description Type
code The response code can have following values:   success, failurestring
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 1

[
  {
    "code": "success",
     "snapshotId": "10",
    "details": "",
    "jobStatus": "done" 
  }
]

Sample Response 2

[
  {
    "code": "failure",
     "snapshotId": "",
     "details": "StartDate Validation Failed: Please try a startDate before date: 2019-03-01/endDate validation failed :   
      Reports are available for endDate till date: 2019-03-01 /",
     "jobStatus": "" 
  }
]

Sample Response 3

[
  {
     "code": "success",
     "snapshotId": "11",
     "details": "",
     "jobStatus": "done" 
  }
]

Sample Response 4

[
  {
     "code": "success",
     "snapshotId": "15",
     "details": "",
     "jobStatus": "done" 
  }
]

Sample Response 5

[
  {
     "code": "success",
     "snapshotId": "16",
     "details": "",
     "jobStatus": "pending" 
  }
]

Sample Response 6

[
  {
     "code": "success",
     "snapshotId": "17",
     "details": "",
     "jobStatus": "pending" 
   }
]

Sample Response 7

[
  {
     "code": "success",
     "snapshotId": "18",
     "details": "",
     "jobStatus": "pending" 
  }
]

Sample Response 8

[
  {
     "code": "success",
     "snapshotId": "19",
     "details": "",
     "jobStatus": "pending" 
  }
]

Sample Response 9

[
  {
     "code": "success",
     "snapshotId": "20",
     "details": "",
     "jobStatus": "pending" 
  }
]

Sample Response 10

[
  {
     "code": "success",
     "snapshotId": "21",
     "details": "",
     "jobStatus": "pending" 
  }
]

Retrieve Snapshot Reports

Description: You can retrieve report 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 in zip file will be CSV for Snapshot Reports.
  • Reports for Sponsored Brand campaigns:Report snapshots provide Sponsored Brand campaign metrics like they do for non- Sponsored Brand campaigns, however, following are some rules that specifically govern metrics for Sponsored Brand campaigns: 
    • Clicks and Impressions are attributed as per clicks and display for each item displayed in Sponsored Brand placement 
    • Sponsored Brand placement is only available on Search page; hence its metrics are included in Search page only for page type report 
    • Clicks and Impressions for logo are tracked under Item report; the revenue metrics for logo are based on related and brand sales 
    • In the Item report snapshot (for Sponsored Brand campaigns), you will see “Logo” as a reported item name with item Id as ‘1001’.
    • Sponsored Brand campaigns are not included in Item-Keyword Report 

Sample Request

curl -X GET\
"https://developer.api.stg.walmart.com/api-proxy/service/WPA/Api/v1/api/v1/snapshot?advertiserId=600001&snapshotId=1&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:
pending, processing, done, failed, expired 		string
details URL of the snapshot file once jobStatus reaches to state “done”   string
code The response code can have following values:   success, failure string

Note:

  • TTL (Time to Live) for files generated is one day

If you want to retrieve keyword report based on the response for Create Report Request (Sample Response 1)

Sample Response 1

[ 
  {
    "code": "success",
     "snapshotId": "10",
    "details": "https://advertising.walmart.com/file/10",
    "jobStatus": "done"
  }
]

The snapshot file is in CSV format that includes response for each report type. You can request multiple report types in one request; however, the response would be captured in one zip/gzip file as explained in the “Types of Format” section.. It will have single CSV file returning response for all report types.

Example of the content of snapshot with id “10”. The file format is “CSV”:

"date",
"campaignId",
"adGroupId",
"keywordId”,
"biddedKeywords",
"matchType",
"searchedKeyword",
"adSpend",
"numAdsShown",
"numAdsClicks",
"clickRevenue3days",
"unitsSold3days",
"viewRevenue3days",
"brandClickRevenue3days",
"brandViewRevenue3days",
"relatedClickRevenue3days",
"offlineClickRevenue3days",
"offlineViewRevenue3days",
"revenue3days",
"2019-02-28",600001,600001, ,"bkey1","exact","key1",6,100,10,2,7,23,25,3,0,15,16,18,0,4,8,0,0,0
"2019-02-28",600001,600001, ,"bkey2","phrase","key2",6,100,10,2,7,23,25,3,0,15,16,18,0,4,8,16,0,16 
"2019-02-28",600001,600003, ,"bkey5","exact","key5",6,100,10,2,7,23,25,3,0,15,16,18,0,4,8,60,0,60.6
"2019-02-28",600001,600003, ,"bkey6","phrase","key6",6,100,10,2,7,23,25,3,0,15,16,18,0,4,8,16,0,16

Note:

  • maximum character length of 60 characters is returned for searchedKeyword
  • searchedKeyword field will provide:
    • search query entered by the site visitor, in an event when an ad is delivered on Search Carousel or Search In-grid placements
    • Item ID (anchor item) specific to the Item Page on which the ad is delivered, in an event when an ad is delivered on the item page placements

If you want to retrieve adGroup report based on the response for Create Report Request (Sample Response 2)

Sample Response 2

[ 
  {
    "code": "success",
    "snapshotId": "11",
    "details": "https://advertising.walmart.com/file/11",
    "jobStatus": "done"
  }
]

Example of the content of snapshot with id “11”. The file format is “CSV”:

"campaignId",
"adGroupId",
"adGroup",
"adSpend",
"numAdsShown",
"numAdsClicks",
"clickRevenue3days",
"unitsSold3days",
"viewRevenue3days",
"brandClickRevenue3days",
"brandViewRevenue3days",
"relatedClickRevenue3days",
"revenue3days",
"offlineClickRevenue3days",
"offlineViewRevenue3days"
 600001,600001, "Ad Group 1p", 12, 200, 20, 4, 46, 6, 30, 36, 8, 76, 76.6, 10
600001,600003," Another Ad Group 1p", 12, 200, 20, 4, 46, 6, 30, 36, 8, 76, 76.6, 10

If you want to retrieve itemKeyword report based on the response for Create Report Request (Sample Response 3)

Sample Response 3

[ 
  {
    "code": "success",
    "snapshotId": "15",
    "details": "https://advertising.walmart.com/file/15",
    "jobStatus": "done"
  }
]

Example of the content of snapshot with id “15”. The file format is “zip CSV”:

"ds",
"campaignId",
"adGroupId",
"itemId",
"keywordId",
"biddedKeywords",
"searchedKeyword",
" matchType",
" adSpend",
"numAdsShown",
"numAdsClicks",
"clickRevenue3days",
"clickRevenue30days",
"unitsSold3days",
"unitsSold30days",
"viewRevenue3days",
"viewRevenue30days",
"brandClickRevenue3days",
"brandClickRevenue30days",
"brandViewRevenue3days",
"brandViewRevenue30days",
"relatedClickRevenue3days",
"relatedClickRevenue30days",
2019-02-10,600001,600001, 1000001,600001, bid_kw1, key1, exact, 10.0,12.0,13.0,34.0,21.0,15.0,37.0,31.0,23.0,66.0,51.0,17.0,55.0,
33.0,25.0
2019-02-10,600001,600001, 1000001,600001, bid_kw1, key2, exact, 10.0,12.0,13.0,34.0,21.0,15.0,37.0,31.0,23.0,66.0,51.0,17.0,55.0,
33.0,25.0
2019-02-10,600001,600001, 1000002,600001, bid_kw2, key3, exact, 10.0,12.0,13.0,34.0,21.0,15.0,37.0,31.0,23.0,66.0,51.0,17.0,55.0,
33.0,25.0
2019-02-10,600001,600001, 1000003,600001, key4, exact, 10.0,12.0,13.0,34.0,21.0,15.0,37.0,31.0,23.0,66.0,51.0,17.0,55.0,
33.0,25.0
2019-02-11,600001,600001, 1000001,600001, bid_kw1, key1, exact,10.0,12.0,13.0,34.0,21.0,15.0,37.0,31.0,23.0,66.0,51.0,17.0,55.0,33.0,25.0
2019-02-11,600001,600001, 1000001,600001, bid_kw1, key2, exact, 10.0,12.0,13.0,34.0,21.0,15.0,37.0,31.0,23.0,66.0,51.0,17.0,55.0,
33.0,25.0
2019-02-11,600001,600001,1000002 ,600001, bid_kw2, key3, exact,10.0,12.0,13.0,34.0,21.0,15.0,37.0,31.0,23.0,66.0,51.0,17.0,55.0,33.0,25.0
2019-02-11,600001,600001,1000003,600001, key4, exact,10.0,12.0,13.0,34.0,21.0,15.0,37.0,31.0,23.0,66.0,51.0,17.0,55.0,33.0,25.0
2019-02-12,600001,600001,1000001, 600001, bid_kw1, key1, exact,10.0,12.0,13.0,34.0,21.0,15.0,37.0,31.0,23.0,66.0,51.0,17.0,55.0,33.0,25.0
2019-02-12,600001,600001,1000001, 600001, bid_kw1, key2, exact,10.0,12.0,13.0,34.0,21.0,15.0,37.0,31.0,23.0,66.0,51.0,17.0,55.0,33.0,25.0
2019-02-12,600001,600001,1000002, 600001, bid_kw2, key3, exact,10.0,12.0,13.0,34.0,21.0,15.0,37.0,31.0,23.0,66.0,51.0,17.0,55.0,33.0,25.0
2019-02-12,600001,600001,1000003,600001, key4, exact,10.0,12.0,13.0,34.0,21.0,15.0,37.0,31.0,23.0,66.0,51.0,17.0,55.0,33.0,25.0
2019-02-13,600001,600001,1000001, 600001, bid_kw1, key1, exact,10.0,12.0,13.0,34.0,21.0,15.0,37.0,31.0,23.0,66.0,51.0,17.0,55.0,33.0,25.0
2019-02-13,600001,600001,1000001, 600001, bid_kw1, key2, exact,10.0,12.0,13.0,34.0,21.0,15.0,37.0,31.0,23.0,66.0,51.0,17.0,55.0,33.0,25.0
2019-02-13,600001,600001,1000002, 600001, bid_kw2, key3, exact,10.0,12.0,13.0,34.0,21.0,15.0,37.0,31.0,23.0,66.0,51.0,17.0,55.0,33.0,25.0
2019-02-13,600001,600001,1000003,600001, key4, exact,10.0,12.0,13.0,34.0,21.0,15.0,37.0,31.0,23.0,66.0,51.0,17.0,55.0,33.0,25.0

Note:

  • maximum character length of 60 characters is returned for searchedKeyword
  • searchedKeyword field will provide:
    • search query entered by the site visitor, in an event when an ad is delivered on Search Carousel or Search In-grid placements
    • Item ID (anchor item) specific to the Item Page on which the ad is delivered, in an event when an ad is delivered on the item page placements

If you want to retrieve item health report created under Create Report Request (Sample Response 4)

Sample Response 4

[ 
  {
    "code": "success",
    "snapshotId": "16",
    "details": "https://advertising.walmart.com/file/16",
    "jobStatus": "done"
  }
]

Example of the content of snapshot with id “16”. The file format is “CSV:

“asOf"
"itemId",
"itemType",
"publishStatus",
"campaignIds",
"adGroupIds",
"pageViews",
"pageViewLastWeek",
"buyBoxPct",
"buyBoxPctLastWeek",
"availabilityPct",
"availabilityPctLastWeek",
“listingQualityScore”,
“contentScore”,
“ratingScore”,
“offerScoreCampaign”,
"2019-02-28", “12345577", "Base", "Published", "[600001, 600002] ", "[600001, 600002]", 0, 156432, 0,89.68, 0, 88.37,71.41, 95.46, 92.23, 44.97
"2019-02-28", "510982984", "Base", "Published", "[600001, 600002] ", "[600001, 600002]", 16734, 56342, 58.64, 71.4, 93.88, 85.48, 66.87, 91.24, 80.67, 44.97
"2019-02-28", "98234546", "Base", "Published", "[600001, 600002] ", "[600001, 600002]", 116734, 156342, 94.07, 89.68, 90.56, 88.37, 61.70, 74.59, 78.20, 43.88

If you want to retrieve item health V2 report for 14-day attribution window created under Create Report Request (Sample Response 5)

Sample Response 5

[
  {
    "code": "success",
    "snapshotId": "17",
    "details": "https://advertising.walmart.com/file/17",
    "jobStatus": "done"
  }
]

Example of the content of snapshot with id “17”. The file format is “CSV“: 

“asOf"
"itemId",
"primaryVariantId",
"publishStatus",
"campaignIds",
"adGroupIds",
"pageViews",
"pageViewLastWeek",
"buyBoxPct",
"buyBoxPctLastWeek",
"availabilityPct",
"availabilityPctLastWeek",
“listingQualityScore”,
“contentScore”,
“ratingScore”,
“offerScoreCampaign”,
"2019-02-28", “12345577", "12345577", "Published", "[600001, 600002] ", "[600001, 600002]", 0, 156432, 0,89.68, 0, 88.37,71.41, 95.46, 92.23, 44.97
"2019-02-28", "510982984", "12345577", "Published", "[600001, 600002] ", "[600001, 600002]", 16734, 56342, 58.64, 71.4, 93.88, 85.48, 66.87, 91.24, 80.67, 44.97
"2019-02-28", "98234546", "12345577", "Published", "[600001, 600002] ", "[600001, 600002]", 116734, 156342, 94.07, 89.68, 90.56, 88.37, 61.70, 74.59, 78.20, 43.88

If you want to retrieve keyword report for 14-day attribution window created under Create Report Request (Sample Response 10)

Sample Response 10

[ 
  {
    "code": "success",
    "snapshotId": "21",
    "details": "https://advertising.walmart.com/file/21",
    "jobStatus": "done"
  }
]

Example of the content of snapshot with id “18”. The file format is “CSV“:

Note: All the view metrics (brandViewRevenue, offlineViewRevenue, viewRevenue) are no longer supported after 3-1-2021 and their values will be 0 with effect from this date.

"campaignId",
"adGroupId",
"keywordId",
"biddedKeywords",
"matchType",
"searchedKeyword",
"adSpend",
"numAdsShown",
"numAdsClicks",
"brandClickRevenue14days",
 "brandViewRevenue14days",
 "offlineClickRevenue14days",
"relatedClickRevenue14days",
"clickRevenue14days",
"offlineViewRevenue14days",
"unitsSold14days",
"viewRevenue14days"
600001, 600001, , "Health/Fsa And Hsa Shop", "category", "key1", 6, 100, 10, 31, 32, 0, 29, 27, 0, 38, 33
600001, 600001, , " Health/Fsa And Hsa Shop2 ", " category ", “key2”, 6, 100, 10, 31, 32, 0, 29, 27, 16, 38, 33
600001, 600003, , " Health/Fsa And Hsa Shop5", " category ", "key5", 6, 100, 10, 31, 32, 0, 29, 27, 60.6, 38, 33
600001, 600003, , " Health/Fsa And Hsa Shop6", " category ", "key6", 6, 100, 10, 31, 32, 0, 29, 27, 16, 38, 33

Note:

  • maximum character length of 60 characters is returned for searchedKeyword
  • searchedKeyword field will provide:
  • search query entered by the site visitor, in an event when an ad is delivered on Search Carousel or Search In-grid placements
  • Item ID (anchor item) specific to the Item Page on which the ad is delivered, in an event when an ad is delivered on the item page placements

Definition of Various Parameters Generated Across the Snapshot Reports

Note: All the view metrics (brandViewRevenue, offlineViewRevenue, viewRevenue) are no longer supported after 3-1-2021 and their values will be 0 with effect from this date.

Element  Description Type
adGroup Name of the ad group string
adGroupId Id of the ad group integer
adSpend   The amount of budget spent in dollars

Note: adSpend can be retrieved by the formula: CPC*clicks CPC Bid amount will be restricted to first two decimal places for advertisers. Any decimal digit beyond the first 2 digits will be truncated without rounding off   		double
biddedKeywords   Actual keyword that was used in bidding

Note: biddedKeywords column will provide bidded category path for rows reporting on category bids. i.e. when matchType is category   		string
brand Different brands of items in your campaign    string
brandClickRevenue3days   Attributed sales based off the direct click of the same brand as the advertised item indollars, over 3 day click.

This can be further divided into two parameters to determine the separate sales revenue generated from P&D (Pickup and Delivery) or Walmart.com as brandClickShippingRevenue3days, brandClickPickupnDeliveryRevenue3days		double
brandClickRevenue30days Attributed sales based off the direct click of the same brand as the advertised item in dollars, over 30 day click.

This can be further divided into two parameters to determine the separate sales revenue generated from P&D (Pickup and Delivery) or Walmart.com as brandClickShippingRevenue30days, brandClickPickupnDeliveryRevenue30day		double
brandClickRevenue14daysAttributed sales based off the direct click of the same brand as the advertised item in dollars, over 14 day click.

This can be further divided into two parameters to determine the separate sales revenue generated from P&D (Pickup and Delivery) or Walmart.com as brandClickShippingRevenue14days, brandClickPickupnDeliveryRevenue14days 		double
brandViewRevenue3daysAttributed sales based off the view of the same brand as the advertised item in dollars, over 3 day click double
brandViewRevenue30daysAttributed sales based off the view of the same brand as the advertised item in dollars, over 30 day click double
brandViewRevenue14daysAttributed sales based off the view of the same brand as the advertised item in dollars, over 14 day click double
campaignId Id of the campaign integer
category Categories of the items in your campaign   string
clickRevenue3days Attributed sales revenue based off the direct click of the advertised item in dollars, over 3 day click.

This can be further divided in two parameters to determine the separate sales revenue generated from P&D (Pickup and Delivery) or Walmart.com as clickShippingRevenue3days, clickPickupnDeliveryRevenue3days   		double
clickRevenue30days Attributed sales revenue based off the direct click of the advertised item in dollars, over 30 day click.

This can be further divided in two parameters to determine the separate sales revenue generated from P&D (Pickup and Delivery) or Walmart.com as clickShippingRevenue30days , clickPickupnDeliveryRevenue30days   		double
clickRevenue14days Attributed sales revenue based off the direct click of the advertised item in dollars, over 14 day click.

This can be further divided in two parameters to determine the separate sales revenue generated from P&D (Pickup and Delivery) or Walmart.com as clickShippingRevenue14days, clickPickupnDeliveryRevenue14days   		double
ds Specific day and time for which the report is pulled. This is available only for item keyword report currently. date-time
itemId Id of the item string
image name of the item string
keywordId Id of the keyword

Note:
1) keywordId holds good only for keywords added in manual campaigns. It will be returned empty for a keyword in auto campaign.
2) For Sponsored Brand campaigns only: In snapshot report, keywordId will be empty for a row, showing category performance data i.e. the keywordId will be empty when the matchType is category.		integer
matchType Match type is a set of options to decide matching criteria for keywords

Match type values can be:  exact, phrase, broad, category(*category for rows, reporting on category bids in keyword snapshot report) 		string
name Name of the item   string
numAdsClicks   Number of ads clicks integer
numAdsShown Number of ads shown integer
offlineClickRevenue3days Attributed offline sales revenue based off direct click of the advertised item, over 3 day click. It will have a value only for 1Ps and ‘0’ for 3Ps   double
offlineClickRevenue30days Attributed offline sales revenue based off direct click of the advertised item, over 30 day click. It will have a value only for 1Ps and ‘0’ for 3Ps   double
offlineClickRevenue14days Attributed offline sales revenue based off direct click of the advertised item, over 14 day click. It will have a value only for 1Ps and ‘0’ for 3Ps   double
offlineViewRevenue3days Attributed offline sales revenue based off the view of the advertised item, over 3 day click. It will have a value only for 1Ps and ‘0’ for 3Ps   double
offlineViewRevenue30days Attributed offline sales revenue based off the view of the advertised item, over 30 day click. It will have a value only for 1Ps and ‘0’ for 3Ps   double
offlineViewRevenue14days Attributed offline sales revenue based off the view of the advertised item, over 14 day click. It will have a value only for 1Ps and ‘0’ for 3Psdouble
pageType Different page types for page specific reports.

Possible page type values are are: browse, item, search, topic, category, homepage, other (any other pages not falling into the categories above) 		string
platform   The platform where the campaign is running.

The values are: mobile, desktop, app, others 		string
revenue3days Total Revenue based on 3 day click and 1 day view attribution in dollars double
revenue30days Total Revenue based on 30 day click and 1 day view attribution in dollars double
relatedClickRevenue3days Attributed sales revenue based off the direct click of the same brand and category as the advertised item in dollars, over 3 day click.

This can be further divided in two parameters to determine the separate sales revenue generated from P&D (Pickup and Delivery) or Walmart.com as relatedClickShippingRevenue3days, relatedClickPickupnDeliveryRevenue3days 		double
relatedClickRevenue30days Attributed sales revenue based off the direct click of the same brand and category as the advertised item in dollars, over 30 day click.

This can be further divided in two parameters to determine the separate sales revenue generated from P&D (Pickup and Delivery) or Walmart.com as clickShippingRevenue30days, clickPickupnDeliveryRevenue30days   		double
relatedClickRevenue14days Attributed sales revenue based off the direct click of the same brand and category as the advertised item in dollars, over 14 day click.

This can be further divided in two parameters to determine the separate sales revenue generated from P&D (Pickup and Delivery) or Walmart.com as clickShippingRevenue14days, clickPickupnDeliveryRevenue14days   		double
searchedKeyword searchedKeyword field will provide:
1) search query entered by the site visitor, in an event when an ad is delivered on Search Carousel or Search In-grid placements
2) Item ID (anchor item) specific to the Item Page on which the ad is delivered, in an event when an ad is delivered on the item page placements

Note: maximum character length of 60 characters is returned for searchedKeyword 		string
unitsSold3days How many of your items were sold based on a direct click, for a 3 days windowdouble
unitsSold30days How many of your items were sold based on a direct click, for 30 days window double
unitsSold14days   How many of your items were sold based on a direct click, for 14 days window   double
viewRevenue3days Attributed sales revenue based off the view of the advertised item in dollars, over 3 day click. double
viewRevenue30days Attributed sales revenue based off the view of the advertised item in dollars, over 30 day click. double
viewRevenue14days   Attributed sales revenue based off the view of the advertised item in dollars, over 14 day click.   double
placement   The location or placement to serve ads for keyword campaigns.

Possible values are: Search In-grid, Carousel, Buybox, Others 		string

Definition of Various Parameters Generated Across the Item Health Reports

Definition of Various Parameters Generated Across the itemHealthV2 Report

Element Description Type
asOf The date for which the Item Health report is available.

Note: It will only be available for the most recent date for which it has been processed for. Usually it is expected to be from day prior to yesterday, unless there is any delay. The format is yyyy-MM-dd.   		date
itemId Id of the relevant item integer
primaryVariantId Id of the primary variant for the given itemstring
publishStatus Status of the SKU. It has following values: Published, Unpublished string
campaignIds  Ids of all campaigns which include the relevant item

Note: the campaignIds included will only be for campaigns that are live for the date the report was generated 		integer
adGroupIds Ids of all ad groups which include the relevant item integer
pageViews Number of page visits the concerned item received integer
pageViewLastWeek Number of page visits the concerned item received in the last seven daysinteger
buyBoxPct The percentage of number of times the seller/supplier is winning the buybox for all item page visits, for a given item on the day when the report is generateddouble
buyBoxPctLastWeek The percentage of number of times the seller/supplier is winning the buybox for all item page visits, for a given item. It is calculated for a window including the day for which the report was generated and 6 days preceding it.   double
availabilityPct The percentage of times an item was in stock on the day for which the report is generated. double
availabilityPctLastWeek The percentage of times an item was in stock for a window including the day for which the report was generated and 6 days preceding it. double
listingQualityScore Listing Quality (i.e., OLQ) is a score between 0-100 that gives insights into how an item is performing based on factors that affect consumers and their purchase decisions

Note: The value of this parameter will be populated only for 3P sellers. It will show as null for their 1P counterparts 		double
contentScore Content and Discoverability score is a metric based on factors like category, description, product title, key features, attributes, images, rich media, and gives insights content quality on item page

Note: The value of this parameter will be populated only for 3P sellers. It will show as null for their 1P counterparts 		double
ratingScore Rating score is a metric based on customer feedback and ratings on Walmart.com and gives insights into item quality and whether the purchased item has met the needs of the customer.

Note: The value of this parameter will be populated only for 3P sellers. It will show as null for their 1P counterparts 		double
offerScore Offer score is a metric based on factors like item price, shipping speed, in-stock rate/inventory, shipping price, and gives insights whether the item listing is competitive when compared with other retail platforms.

Note: The value of this parameter will be populated only for 3P sellers. It will show as null for their 1P counterparts 		double

Definition of Various Parameters Generated Across the itemHealth Report

Element Description Type
asOf The date for which the Item Health report is available.

Note: It will only be available for the most recent date for which it has been processed for. Usually it is expected to be from day prior to yesterday, unless there is any delay. The format is yyyy-MM-dd.   		date
itemId Id of the relevant item integer
itemType Identifies the type for a given item.
With variant bidding launch, all the items will have itemType as `Variant. 		string
publishStatus Status of the SKU. It has following values: Published, Unpublished string
campaignIds  Ids of all campaigns which include the relevant item

Note: the campaignIds included will only be for campaigns that are live for the date the report was generated 		integer
adGroupIds Ids of all ad groups which include the relevant item integer
pageViews Number of page visits the concerned item received integer
pageViewLastWeek Number of page visits the concerned item received in the last seven daysinteger
buyBoxPct The percentage of number of times the seller/supplier is winning the buybox for all item page visits, for a given item on the day when the report is generateddouble
buyBoxPctLastWeek The percentage of number of times the seller/supplier is winning the buybox for all item page visits, for a given item. It is calculated for a window including the day for which the report was generated and 6 days preceding it.   double
availabilityPct The percentage of times an item was in stock on the day for which the report is generated. double
availabilityPctLastWeek The percentage of times an item was in stock for a window including the day for which the report was generated and 6 days preceding it. double
listingQualityScore Listing Quality (i.e., OLQ) is a score between 0-100 that gives insights into how an item is performing based on factors that affect consumers and their purchase decisions

Note: The value of this parameter will be populated only for 3P sellers. It will show as null for their 1P counterparts 		double
contentScore Content and Discoverability score is a metric based on factors like category, description, product title, key features, attributes, images, rich media, and gives insights content quality on item page

Note: The value of this parameter will be populated only for 3P sellers. It will show as null for their 1P counterparts 		double
ratingScore Rating score is a metric based on customer feedback and ratings on Walmart.com and gives insights into item quality and whether the purchased item has met the needs of the customer.

Note: The value of this parameter will be populated only for 3P sellers. It will show as null for their 1P counterparts 		double
offerScore Offer score is a metric based on factors like item price, shipping speed, in-stock rate/inventory, shipping price, and gives insights whether the item listing is competitive when compared with other retail platforms.

Note: The value of this parameter will be populated only for 3P sellers. It will show as null for their 1P counterparts 		double

Rate limits on API operations

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.