Guides

Create Report Snapshot

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
Reporting data may be delayed by 24 to 48 hours from the time of the request.

Note: The POST functionality is similar for both Onsite and Offsite display

📘

URL: POST /api/v1/snapshot/report

Definition of Retrievable Reports

The following table lists all supported reportType values and whether the report can be retrieved for Onsite Display and Offsite Display (TTD) campaigns.

reportTypeReport Name on UIOnsite DisplayOffsite Display
campaignProvides overall performance metrics at the campaign level✅ Yes✅ Yes
lineItemProvides ad group level performance metrics.✅ Yes✅ Yes
tacticProvides tactic level performance metrics.✅ Yes✅ Yes
skuProvides item level performance for items in the campaign's itemset✅ Yes✅ Yes
bidThe performance of bids for on-site display auction campaigns✅ Yes❌ No
newBuyerAnalyzes buying frequency of ad exposed shoppers✅ Yes✅ Yes
creativeProvides performance insights at the creative level✅ Yes❌ No
basketAnalysisShows the top 10 online and top 10 in-store categories and sub-categories most frequently purchased together with advertised items in shopper baskets.
Report applicable only for Onsite display

Note: this report is available only in End of Campaign reporting starting 30 days after the campaign ends and is not available for campaigns with spend below $150K		✅ Yes❌ No
ivtViewabilityProvides MRC accredited Invalid Traffic & Viewability metrics.
Report applicable only for Onsite display
✅ Yes❌ No
📌

Note:

SKU reports can produce very large files. We strongly recommend using a date range of 15 days or fewer (vs. the 60-day limit for other reports); if your ad campaign includes many items, reduce the date range even further to ensure the report completes reliably

Request 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
Note: The reports encompass data starting from midnight (00:00:00 hrs ET) on this particular date		 date Y Date should be in format: `yyyy-MM-dd`
endDate The last day to be considered in the performance report snapshot. It cannot be the current date.
Note:
  • The reports encompass data until the end of the day (23:59:59 hrs ET) for this particular date
  • 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`
attributionWindow Window for attribution
Note: attributionWindow is applicable only when reportType = sku		 string Optional and applicable only for `sku` report Allowed Values:
  • days14: Report will include 14-day attribution columns If a user selects this value
  • days30: Report will include 30-day attribution columns if a user selects this value
salesChannel Sales channel for the transaction
Note: salesChannel is applicable only when reportType = sku		 string Optional and applicable only for `sku` report If specified, the metrics applicable for the specified sales channel are returned.
Allowed Values: `stores`, `online`, `acc`
  • stores: If specified, only metrics prefixed with storeAttributed are returned
  • online: If specified, only metrics prefixed with pickupAttributed, deliveryAttributed are returned
  • acc: If specified, only metrics prefixed with accAttributed are returned
itemsetType Type of item set
Note: itemsetType is applicable only when reportType = sku		 string Optional and applicable only for `sku` report If specified, the metrics applicable for the specified itemsetType are returned.
Allowed Values: `halo`, `featured`, `total`
  • halo: if specified, only metrics are returned that have “Halo“ in it
  • featured: if specified, only metrics are returned that have “Featured“ in it
  • total: if specified, only metrics are returned that have “Halo“ or “Featured“ in it
reportType Type of report to be retrieved string Y Types of Report: `campaign`, `lineItem`, `tactic`, `sku`, `bid`, `newBuyer`, `creative`, `basketAnalysis`, `ivtViewability`
Note: basketAnalysis, ivtViewability reports are available only for Onsite display
reportMetrics Choose the metrics type for your snapshot
Note: If you omit this parameter in your request, you will receive all the metrics that are relevant to the selected report type		 string N Please refer to the table **“**[**Definition of Various Parameters Generated Across the Snapshot Reports**](https://developer.walmart.com/advertising-partners/docs/definition-of-various-parameters-generated-across-the-snapshot-reports)**”** for detailed information on report metrics
scope Controls the aggregation level at which report metrics are returned. string N Possible values: `CAMPAIGN`, `CAMPAIGN_GROUP`
  • When `reportType` is set to `campaign`, `lineItem`, `sku`, or `newBuyer`, the default value of `scope` = `CAMPAIGN`
  • When `reportType` is set to `creative`, `tactic`, `ivtViewability` or `bid`: `scope` = `CAMPAIGN_GROUP` is not supported and will return an error.
  • n`, `lineItem`, `sku`, `newBuyer` reports will have 2 additional fields: `campaignGroupId` and `campaignGroupName`
  • If `scope` isn't defined in the request, it will be set to `CAMPAIGN` by default.
buyerLookbackWindow Lookback time frame used to define New Buyers as ad-exposed buyers who have not purchased featured or halo items during that period, measured from the first attributed transaction.
Note: applicable only for New Buyer reports		 string N Allowed Values: `months6`, `months12`, `months18`, `months24`, `months36`


Notes on scope parameter

  • When scope = campaign_group, the API returns rows only for campaigns that belong to a campaign group. Standalone campaigns, that are not part of any groups, are excluded.
  • Campaign groups can span multiple advertisers. You can retrieve a group report only if you have view access to all campaigns in that group.
  • New buyer Report: For campaigns that are in a group, when scope = campaign_group metrics are returned at the campaign_group level and are identical across all campaigns in that group.
    To download newBuyer reports for campaigns that are not in any campaign group, use scope = campaign

👉

Rules

  1. No-data behavior: If a report is generated successfully but no data is available for a metric or field, the report displays 0.
  2. Date range behavior: Reporting data is returned for the startDate and endDate specified in the request, except where a report-specific rule states otherwise.
  3. Unsupported field usage: Optional fields are only valid for the report types explicitly listed in this section. If an optional field is provided for an unsupported reportType, the request should return a validation error.
  4. Report type values:
    1. reportType must be one of the supported enum values: campaign, lineitem, tactic, sku, newBuyer, bid, creative, ivtViewability, salesLift, basketAnalysis
    2. bid reports are refreshed near real-time.
  5. Field applicability and defaults:
    Field Applies To Allowed Values Default Validation / Behavior
    itemsetType sku only featured, halo, total None Optional. If provided for any report type other than sku, return a validation error.
    attributionWindow sku only days14, days30 None Optional. If provided for any report type other than sku, return a validation error.
    salesChannel sku only online, stores, acc None Optional. If provided for any report type other than sku, return a validation error.
    buyerLookbackWindow newBuyer only months6, months12, months18, months24, months36 months12 Optional. If omitted for newBuyer, months12 is used. If provided for any report type other than newBuyer, return a validation error.
    scope Varies by reportType CAMPAIGN, CAMPAIGN_GROUP CAMPAIGN Optional. If omitted, the default value CAMPAIGN is used for those reports for which scope is supported
  6. buyerLookbackWindow Rules:
    1. buyerLookbackWindow is optional and is supported only when reportType = newBuyer.
    2. Default Behavior: If buyerLookbackWindow is omitted for a New Buyer report, the default value is: "buyerLookbackWindow": ["months12"]
    3. Supported Values: ["months6", "months12", "months18", "months24", "months36"]
    4. Eligibility Rules:
      1. The following buyer lookback windows are supported only for eligible new campaigns (start date is on or after 2026-06-01, using last_touch attribution): ["months6", "months18", "months24", "months36"]
      2. For older campaigns, the New Buyer report continues to use the default 12-month buyer lookback window, even if another buyerLookbackWindow value is provided in the request.
  7. Date Range Behavior for New Buyer Reports:
    1. Campaign Type Behavior
      Eligible new campaigns (start date >= 2026-06-01) using last-touch attribution New Buyer data is returned for the startDate and endDate specified in the request.
      Older or ineligible campaigns New Buyer data is returned as campaign-to-date metrics for the lifetime of the line item.
  8. scope Rules
    1. The scope field determines whether the report is generated at the campaign level or campaign group level.
    2. Default value: If scope is omitted, the following defaults apply:
      1. Report Type Default Scope
        campaign CAMPAIGN
        lineitem CAMPAIGN
        sku CAMPAIGN
        newBuyer CAMPAIGN
        salesLift CAMPAIGN
    3. Unsupported CAMPAIGN_GROUP Scope
      1. The following report types do not support scope = CAMPAIGN_GROUP: creative, tactic, bid, ivtViewability, basketAnalysis
      2. If scope = CAMPAIGN_GROUP is provided for any of these report types, the request returns a validation error.
    4. Report-Specific Scope Behavior:
      1. New Buyer Report
        1. For reportType = newBuyer, both CAMPAIGN and CAMPAIGN_GROUP scope may be supported.
        2. New buyer report are generated at both campaign and campaign groups levels.
        3. Hence, when scope = CAMPAIGN_GROUP, campaigns that belong to the same campaign group will show the same New Buyer metric values.
      2. Sales Lift Report
        1. Sales lift studies are run for campaign groups and standalone campaigns.
        2. Sales Lift report behavior depends on whether the campaign belongs to a campaign group:
          1. Campaign Scenario Behavior
            Campaign is part of a campaign group Sales Lift results are available at the campaign group level and can be downloaded with scope = CAMPAIGN_GROUP

            Campaigns in the same campaign group may show identical Sales Lift values because the underlying study is run at the campaign group level.
            Campaign is not part of any campaign group Sales Lift results are available at the campaign level and can be downloaded with scope = CAMPAIGN.
        3. Basket Analysis Report:
          1. Basket Analysis reports have special availability and scope rules.
          2. Availability: Basket Analysis reports are available only if the below conditions are met for a campaign, else basket analysis data is not available:
            1. Requirement Rule
              Reporting phase End-of-campaign reporting only
              Timing Starting 30 days after the campaign ends
              Minimum spend Campaign spend must be at least $150,000
          3. Scope Behavior:
            1. The scope parameter is not applicable for Basket Analysis reports.
            2. Basket Analysis reports are generated as combined reports and include both campaign and campaign group details, as applicable.
            3. Do not apply a scope filter for reportType = basketAnalysis
            4. Basket Analysis reports are generated for campaign groups and standalone campaigns.
              1. Campaign Scenario Behavior
                Campaign is part of a campaign group Basket Analysis is generated at the campaign group level, not as an individual campaign-level report.
                Campaign is not part of any campaign group Basket Analysis is available for the individual campaign, subject to availability rules.

Response

ElementDescriptionType
code

The response code can have following values:

  • success
  • failure

string
detailsDetails of the error if value of response code is failurestring
snapshotIdID of the snapshotstring
jobStatusIt is an indicator to confirm status of snapshot generation.The possible values of jobStatus are: pending, processing, done, failed, expiredstring

🔧

Troubleshooting Tip:

Slow Report Generation: If your report is taking a long time to generate or if the API response times out, try reducing the date range