Stats

The Stats API endpoint provides capability to retrieve near real time metrics and campaign budget cap-out time on the day of request.

Description: You can retrieve following metrics at advertiser/campaign level in near real-time for the time elapsed on the day of request:

• Ad Spend
• Clicks
• Impressions
• Daily Remaining Budget
• Daily Out of budget Date Time

URL: GET /api/v1/stats

Note:

• We recommend that you do not request near real-time statistics more than once per thirty minutes as the refreshed metrics may not reflect before that
• The Ads exposed attribution (Attributed Units Sold, Attributed Revenue) is not part of near real-time metrics. Only the Ads performance metrics (Ad Spend, Clicks, Impressions) are provided in near real-time metrics.
• Campaign budget type vs Daily remaining budget values:
• For Campaigns that have only daily budget defined – then Daily Remaining Budget (Computed Value)
• For Campaigns that have both total and daily budget defined – then Daily Remaining Budget (Computed Value)
• For Campaigns that have only Total Budget defined – then Daily Remaining Budget is NULL

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 whose performance metrics for today is to be retrieved	integer	Y	Unique numeric identifier
campaignId	The ID of the campaign for which the performance metrics for today needs to be retrieved	integer	N	Unique numeric identifier

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 GET\
 "https://developer.api.stg.walmart.com/api-proxy/service/WPA/Api/v1/api/v1/stats?advertiserId=600002&campaignId=500001&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
campaignId	Id of the advertising campaign whose ad spend is being retrieved	integer
todayAdSpend	The amount of budget spent for current date	double
asOf	Date and time for which the statistics (ad spend, impressions, clicks, daily remaining budget) is requested. Note: The time zone is in PST and time stamp format is 24-hour format	string
adGroupId	Id of the ad group Note: Please ignore this parameter because we now provide stats at campaign level only, and eventually adGroupId will be removed from the response. For now, we will return ‘-1’ for this field.	integer
dailyOutOfBudgetDatetime	An indicator of whether a campaign has yet run out of its assigned daily budget or not. It returns following values: 1. Actual Date and Time: It returns date and timestamp of when the campaign exhausted its daily budget and stopped serving ads. 2. Empty: It returns a blank if the daily budget is not yet exhausted Note: 1. Since it measures spend of daily budget, it only provides date and time stamp for the current day. Also, since it refreshes every day, it will return a blank the subsequent day if the daily budget is not exhausted 2. The time zone is in PST and time stamp format is 24-hour format	string
dailyRemainingBudget	The amount of daily budget left after today’s ad spend is consumed	double
todayImpressions	Total number of impressions counted for today	integer
todayClicks	Total number of clicks counted for today	integer

Sample Response 1

[
  {

    "campaignId": 500001,
    "todayAdSpend":777.0,
    "asOf":  "2021-07-29 18:44",
   "adGroupId": -1,
   "dailyOutOfBudgetDatetime": "2021-07-29 15:41",
    "dailyRemainingBudget": 17.2,
    "todayImpressions": 32421,
     "todayClicks": 14

  }
]

Sample Response 2

Following campaigns’ daily budget is 500 and todayAdSpend is also 500, so dailyRemainingBudget is 0:

[
    {
        "campaignId": 1694255,
        "adgroupId": -1,
        "todayAdSpend": 500.0,
        "asOf": "2022-04-12 20:14",
        "dailyOutOfBudgetDatetime": "2022-04-12 09:08",
        "dailyRemainingBudget": 0.0,
        "todayImpressions": 495627,
        "todayClicks": 1214
    }
]

Sample Response 3

Following campaign has Total Budget defined and Daily Budget is undefined (i.e., Campaign Budget Type: Total). Hence the the Daily Remaining Budget is NULL.

[
  { 
        "campaignId": 531760,
        "adgroupId": -1,
        "todayAdSpend": 52.0,
        "asOf": "2022-04-14 15:18",
        "dailyOutOfBudgetDatetime": null,
        "dailyRemainingBudget": null,
        "todayImpressions": 220,
        "todayClicks": 52
  }
]

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.