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.
General Notes:
Snapshot IDs expire after 24 hours post
generation.
POST
requests under Snapshots v2 endpoint will not be counted towards Rate Limits.
The
reports are snapshots at day level.
POST
and GET requests are through Snapshot v2 endpoints.
The look back period to retrieve Snapshot
Reports via v2 endpoint is 90 Days.
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/v2/snapshot/report
Request 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 for the advertiser. This is the advertising account id. This parameter can take only one advertiser Id for each snapshot report request.
reportType
The type of the performance report for which the snapshot should be generated.
This parameter can take one report type among the above possible report types in each snapshot report request.
reportMetrics
Choose the format type for your snapshot
string
Y
Not all metrics are applicable to all report types. Each report requires at least one dimension to be included in the ‘reportMetrics’ parameter or else the report request will fail. This parameter can take one or more than one report metric among the possible report metrics in each snapshot report request.
Note:Possible reportMetrics values: Dimensions and Metrics that is accepted under reportMetrics, please refer to the table.
reportDate
The snapshot date for the report.
date
Y
The date should be in “yyyy-MM-dd” format. This parameter can take only one report date for the last 90 days each snapshot report request.
Notes on request parameters:
POST requests under Snapshots v2 endpoint will not be counted towards Rate Limits
The reports are snapshots at day level
POST and GET requests are through Snapshot v2 endpoint
In Snapshot v2 endpoint, under reportMetrics, the user can pick and choose the dimensions and metrics as per their needs
Both Dimensions and Metrics are to be requested in reportMetricsparameter. Dimensions helps in defining the level of granularity at which the Metrics are to be retrieved
Each report requires at least one dimension to be included in the reportMetrics parameter else the report request will fail
To get report by campaigns, request report for adGroups and use the campaign ids returned in the report to aggregate the report by campaigns
The format of the report is CSV, and it will be enclosed in “gzip” file format by default
Not all reportMetricsare applicable to all reportTypes
Report Type: itemHealthis not part of Snapshots v2 endpoint. Item Health report will be available only on Snapshots v1 reports
Report Type: itemKeywordis not part of Snapshots v2 endpoint. Item Keyword report will be available only on Snapshots v1 reports
Definition for retrievable Snapshot 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).
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.
videoCampaigns: Video ads campaign report (aggregated performance of all videos broken down by campaign level) will be available by a new reportType “videoCampaigns“
videoKeywords: Video ads keyword report will be available by a new reportType “videoKeyword“
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
You can retrieve report snapshots by providing snapshot id and advertiser id for an advertiser.
URL: GET/api/v2/snapshot
Note:
The format of the report is CSV, and it will be enclosed in “gzip” file format by default.
You can request the following type of snapshots:
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: a. Clicks and Impressions are attributed as per clicks and display for each item displayed in Sponsored Brand placement b. Sponsored Brand placement is only available on Search page; hence its metrics are included in Search page only for page type report c. Report Type:itemHealth/itemHealthV2is not part of Snapshot v2 endpoint Item Health/Item Health V2 report will be available only on Snapshot v1 reports. d. Report Type: itemKeyword is not part of Snapshot v2 endpoint. Item Keyword report will be available only on Snapshot v1 reports
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”:
maximum character length of 60 characters is returned for searchedKeyword
searchedKeyword field will provide: a. search query entered by the site visitor, in an event when an ad is delivered on Search Carousel or Search In-grid placements b. 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)
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
DataType
Element Type
adGroupId
Id of the ad group
integer
Dimension
adGroupName
Name of the ad group
string
Dimension
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
Metric
attributedOrders14days
Attributed orders based off the same brand as the
advertised item in dollars, over 14 day click.
integer
Metric
attributedOrders30days
Attributed orders based off the
same brand as the advertised item in dollars, over 30 day click.
integer
Metric
attributedOrders3days
Attributed orders based off the same brand as the
advertised item in dollars, over 3 day click.
integer
Metric
attributedUnits14days
Attributed units sold based off the
same brand as the advertised item in dollars, over 14 day click.
integer
Metric
attributedUnits30days
Attributed units sold based off the same brand as the
advertised item in dollars, over 30 day click.
integer
Metric
attributedUnits3days
Attributed units sold based off the
same brand as the advertised item in dollars, over 3 day click.
integer
Metric
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 Note: maximum character length of 60 characters is returned for
searchedKeyword.
string
Dimension
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
Dimension
brand
different brands of items in your campaign
string
Dimension
brandAttributedSales14days
Attributed sales based off the
direct click of the same brand as the advertised item in dollars, over 14 day
click.
double
Metric
brandAttributedSales30days
Attributed sales based off the direct click of the same
brand as the advertised item in dollars, over 30 day click.
double
Metric
brandAttributedSales3days
Attributed sales based off the
direct click of the same brand as the advertised item in dollars, over 3 day
click.
double
Metric
campaignId
Id of the campaign
integer
Dimension
campaignName
Name of the campaign
string
Dimension
category
Categories of the items in your campaign
string
Dimension
directAttributedSales14days
Attributed sales revenue based off
the direct click of the advertised item in dollars, over 14 day click.
double
Metric
directAttributedSales30days
Attributed sales revenue based off the direct click of
the advertised item in dollars, over 30 day click.
double
Metric
directAttributedSales3days
Attributed sales revenue based off
the direct click of the advertised item in dollars, over 3 day click.
double
Metric
date
Specific day and time for which the report is pulled.
This is available only for item keyword report currently.
date-time
Dimension
itemId
Id of the item
string
Dimension
itemImage
Item Image URL for items else Logo URL for itemId ‘1001’
string
Dimension
itemName
Name of the item
string
Dimension
keywordId
Id of the keyword
Note
• keywordId holds good only for keywords added in manual campaigns. It will
be returned empty for a keyword in auto campaign.
• For Sponsored Brand campaigns and Sponsored Videos 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
Dimension
matchType
Match type is a set of options to
decide matching criteria for keywords
Match type values can be: exact, phrase, broad
string
Dimension
ntbOrders14days
The number of first-time orders for products within the
brand over a one-year lookback window attributed over 14 days.
integer
Metric
ntbOrders30days
The number of first-time orders for
products within the brand over a one-year lookback window attributed over 30
days.
integer
Metric
ntbOrders3days
The number of first-time orders for products within the
brand over a one-year lookback window attributed over 3 days.
integer
Metric
ntbRevenue14days
The total sales of new-to-brand
orders for products within the brand over a one-year lookback window
attributed over 14 days.
double
Metric
ntbRevenue30days
The total sales of new-to-brand orders for products
within the brand over a one-year lookback window attributed over 30 days.
double
Metric
ntbRevenue3days
The total sales of new-to-brand
orders for products within the brand over a one-year lookback window
attributed over 3 days.
double
Metric
ntbUnits14days
The number of units purchased from new-to-brand orders
for products within the brand over a one-year lookback window attributed over
14 days.
integer
Metric
ntbUnits30days
The number of units purchased from
new-to-brand orders for products within the brand over a one-year lookback
window attributed over 30 days.
integer
Metric
ntbUnits3days
The number of units purchased from new-to-brand orders
for products within the brand over a one-year lookback window attributed over
3 days.
integer
Metric
numAdsClicks
Number of ads clicked
integer
Metric
numAdsShown
Number of ads shown
integer
Metric
pageType
Different page types for page
specific reports.
The values for page types: browse, item, search, topic, category, homepage,
other (any other pages not falling into the categories above)
string
Dimension
placement
The location or placement to serve ads for keyword
campaigns.
Possible values are: Search In-grid, Browse In-grid, Search Carousel, Browse
Carousel, Item Carousel, Buy Box, Home Page, Stock Up
string
Dimension
platform
The platform where the campaign is
running.
The values for platform: mobile, desktop, app, others
string
Dimension
relatedAttributedSales14days
Attributed sales revenue based off the direct click of
the same brand and category as the advertised item in dollars, over 14
day click.
double
Metric
relatedAttributedSales30days
Attributed sales revenue based off
the direct click of the same brand and category as the advertised item
in dollars, over 30 day click.
double
Metric
relatedAttributedSales3days
Attributed sales revenue based off the direct click of
the same brand and category as the advertised item in dollars, over 3
day click.
double
Metric
viewableImpressions
The number of impressions that met
the MRC viewability standard, which is 50% viewable with 2 seconds playback
completed
integer
Metric
videoFirstQuartileViews
The number of impressions where the video was viewed to
25%.
integer
Metric
videoMidpointViews
The number of impressions where the
video was viewed to 50%.
integer
Metric
videoThirdQuartileViews
The number of impressions where the video was viewed to
75%.
integer
Metric
videoCompleteViews
The number of impressions where the
video was viewed to 100%.
integer
Metric
videoUnmutes
The number of impressions where the shopper unmuted the
video.
integer
Metric
video5SecondViews
The number of impressions where the
shopper watched the complete video or 5 seconds, whichever is shorter
integer
Metric
attributedSales3days
Total sales revenue made from units sold over 3 day
click.
double
Metric
attributedSales14days
Total sales revenue made from units sold
over 14 day click.
double
Metric
attributedSales30days
Total sales revenue made from units sold over 30 day
click.
double
Metric
Note: For more information refer Campaign Reporting section here
Report Type availability by Snapshot v1/v2 Endpoint, Campaign Type, and Advertiser Type
Report
Type
Report Availability via Snapshot endpoint
Auto BiddedCampaigns
Keyword Bidded Campaigns
Sponsored Brands
Sponsored Videos
Advertiser Type (1p: Suppliers, 3p: Sellers)
adItem
Both snapshot v1 and snapshot v2
Yes
Yes
Yes
Yes
Both 1p and 3p
adGroup
Both snapshot v1 and snapshot v2
Yes
Yes
Yes
Yes
Both 1p and 3p
platform
Both snapshot v1 and snapshot v2
Yes
Yes
Yes
Yes
Both 1p and 3p
pageType
Both snapshot v1 and snapshot v2
Yes
Yes
Yes
Yes
Both 1p and 3p
keyword
Both snapshot v1 and snapshot v2
No
Yes
Yes
Yes
Both 1p and 3p
brand
Both snapshot v1 and snapshot v2
Yes
Yes
Yes
Yes
Only 1p
category
Both snapshot v1 and snapshot v2
Yes
Yes
Yes
No
Only 1p
placement
Both snapshot v1 and snapshot v2
Yes
Yes
No
No
Both 1p and 3p
itemKeyword
Only via snapshot v1
Yes
Yes
No
No
Both 1p and 3p
videoCampaigns
Only via snapshot v2
No
No
No
Yes
Yes
videoKeywords
Only via snapshot v2
No
No
No
Yes
Yes
itemHealth
Only via snapshot v1
Item health data for all the items
in the active campaigns
Both 1p and 3p
itemHealthV2
Only via snapshot v1
Item health data for all the
items in the active campaigns
Both 1p and 3p
Applicable placements for Campaign Types: Auto Bidded, Keyword Bidded, Sponsored Brands and Sponsored Videos
Placement Name
Auto BidCampaigns
Keyword Bidded Campaigns
Sponsored BrandsCampaigns
Sponsored VideosCampaigns
Search In-grid
Yes
Yes
No
Yes
Browse In-grid
Yes
No
No
No
Search Carousel
Yes
Yes (*Only if enabled in campaign)
No
No
Browse Carousel
Yes
No
No
No
Item Carousel
Yes
Yes (*Only if enabled in campaign)
No
No
Buy Box
Yes
Yes (*Only if enabled in campaign)
No
No
Home Page
Yes
No
No
No
Stock Up
Yes
No
No
No
Sponsored Brands(Top of Search page)
No
No
Yes
No
Description for all ad placements
Placement Name
Description
Search In-grid
Metrics from ads served on the Search In-grid placement
Browse In-grid
Metrics from ads served on the Browse In-grid placement
Carousel
Metrics from ads served on the Search, Browse, and Item
Carousel placements
Buy Box
Metrics from ads served on the Buy Box placement
Homepage
Metrics from ads served on the Home Page placements
Stock up
Metrics from ads served on the Stock Up placement
Other
Metrics where we couldn’t capture which placement the
ads served on.
Frequently Asked Questions (FAQs):
Q. What is View Through Rate?
A. View
Through Rate/VTR is a measurement metric for Sponsored Videos. This is
calculated by dividing the views by the impressions.
Note:This is a derived metric and is not exposed through APIs
Q. What is Click Through Rate for Views?
A. Click
Through Rate for Views (vCTR)is a measurement metric for Sponsored
Videos. This is calculated by dividing the total clicks by the total viewable
impression.
Note:This metric is not exposed through APIs
Rate limits on API operations
There is a rate
limit in place on the allowed number of API operations per hour by an
integrator.
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.
