HomeGuidesAPI Reference
Guides

Request Delivery Estimate V2

Use this API to request delivery estimates or winning impressions forecast for a given ad group.
Note: The API currently supports impression metrics only.

📘

URL: POST/api/v2/deliveryEstimate


Delivery Estimate Request Notes

When requesting an estimate or forecast for an ad group, remember the following for parameters originally set at the campaign level or the ad group level.
If the following request parameters are set at the campaign level:

  • startDate
  • endDate
  • dailyBudget
  • totalBudget
  • deliverySpeed
The API request values for these parameters are disregarded, and the forecast response uses the original campaign values instead.
If the following request parameters are set at the ad group level:
  • startDate
  • endDate
  • targeting
  • maxBid
  • baseBid
  • frequencyCapDay
  • frequencyCapWeek
  • frequencyCapMonth
  • dailyBudget
  • totalBudget
  • deliverySpeed
The values provided in the API request for these parameters override the original values set at ad group level and are used in the forecast response instead

Users can simulate changes by overriding ad group-level settings in the request payload. The API does not modify any stored data.
Note: Currently, the API supports simulation only for ad group-level attributes. Campaign-level budgets or schedules that apply to ad groups are not yet supported for simulation.

Request Parameters

ParametersNotesTypeRequiredPossible Values
advertiserIdID of advertiser integerYUnique numeric identifier
campaignIdID of the campaign containing the ad groupstringYValid campaign ID
adGroupIdID the ad group to forecaststringYValid ad group ID
metricThe list of metrics you are requesting an estimate for.arrayYValues:

  • impressions
  • clicks
  • adSpend



startDateSimulated start date for ad group scheduling

See note regarding parameters set at campaign level or ad group level

here

dateNDate must follow this format:
yyyy-MM-dd'T'HH:mm:ss.SSSXXX

Note: date values are internally converted to EST timezone.
endDateSimulated start date for ad group scheduling. For ad groups that run indefinitely, use the value:
endDate = ‘9999-12-30T00:00:00Z’

See note regarding parameters set at campaign level or ad group level

here

dateNDate must follow this format:
yyyy-MM-dd'T'HH:mm:ss.SSSXXX

Note: date values are internally converted to EST timezone.
targetingA nested array element with following elements:
  • keywords: ONLY APPLICABLE FOR KEYWORD TARGETING
    • keywordText: string data type
    • matchType: string data type Values: broad, exact

    • Note: only Exact match type is allowed for negative keywords

    • contexual: ONLY APPLICABLE FOR CONTEXTUAL TARGETING
      • id: integer data type
      • reach: string data type Values: "tier_1", "tier_2", "tier_3", "tier_4", "tier_5", "tier_6", "tier_7"

    Note: This is how tiers in API call map to the representation on ad center UI: Tier mapping: low = [tier_1, tier_2], mid = [tier_3, tier_4], high = [tier_5, tier_6, tier_7]

    • behavioral: ONLY APPLICABLE FOR BEHAVIORAL TARGETING
      • audienceType: string data type Values:
        • retail
        • brand
        • persona
        • custom
      • attribute: string data type Values:
        • For category:
          • historical
          • predictive
        • For brand:
          • historical
          • predictive
          • lapsed_buyers
        • For persona:
          • lifestyle
          • lifestage
      • id:integer data type
    • runOfSite ONLY APPLICABLE FOR ROS TARGETING:
      string data type, Value: true
    • geoTargets
      • id: integer data type

        Note:
        1. If Geo targeting is not specified, the default Country (US) level targeting will be applied
        2. IDs with isDisabled = true from POST/api/v1/targeting/list cannot be used for targeting

See note regarding limitations of parameters set at campaign level or ad group level

here

The values:
• keywords
• contextual
• behavioral
• runOfSite
• geoTargets
maxBidSimulated maximum bid value for the ad group

See note regarding limitations of parameters set at campaign level or ad group level

here

doubleNValue of max bid. It Must be >=$0.01
baseBidSimulated starting bid for the ad groupdoubleNValue of base bid. Value of base bid. It Must be >=$0.01
frequencyCapDayThe number of times the ad from specific ad group should be shown to the same user in a dayintegerNInteger values between 1 and 511
frequencyCapWeekThe number of times the ad from specific ad group should be shown to the same user in a weekintegerNInteger values between 3 and 511
frequencyCapMonthThe number of times the ad from specific ad group should be shown to the same user in a monthintegerNInteger values between 5 and 511
dailyBudgetSimulated daily budget of the ad group

See note regarding limitations of parameters set at campaign level or ad group level

here

doubleNThe value of daily budget should at least be $0.01
totalBudgetSimulated total budget of ad group

See note regarding limitations of parameters set at campaign level or ad group level

here

doubleNThe value of total budget should at least be $0.01
deliverySpeedDetermines pacing of ad delivery.

See note regarding limitations of parameters set at campaign level or ad group level

here

doubleNValues:
  • frontloaded
  • evenly
timeFramesSpecifies the timeframes for which forecasts should be returned. If not provided, forecasts for all available timeframes will be returned.arrayNValues:

  • daily
  • 30days
  • lifetime



Sample Request

curl --location --request POST 'https://developer.api.us.walmart.com/api-proxy/service/display/api/v1/api/v2/deliveryEstimate' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <auth_token>' \
--header 'WM_SEC.AUTH_SIGNATURE: ***********' \
--header 'WM_CONSUMER.ID: abcde-v123-fa2r-a1fs-asd45f6qef' \
--header 'WM_SEC.KEY_VERSION: 1' \
--header 'WM_CONSUMER.intimestamp: 1565309779' \
--data '{ "advertiserId": 16273802, "campaignId": 90279, "adGroupId": 219338, "metric": [ "impressions","clicks","adSpend"], "timeframes":["daily","30days","lifetime"], "startDate": "2024-06-27T00:00:00Z", "endDate": "2024-12-30T23:59:59Z", "targeting": { "and": [ { "runOfSite": true }, { "geoTargets": [ { "id": 247796189 } ] } ] }, "maxBid": 10, "baseBid": 2, "frequencyCapDay": 50, "frequencyCapWeek": 50, "frequencyCapMonth": 50, "dailyBudget": 100, "totalBudget": 100, "deliverySpeed": "FRONTLOADED" }'

Response

ElementDescriptionType
codeThe response code can have following values:
  • success
  • failure
string
forecastIdforecastId for every successful responsestring
estimatesContains forecasted metrics over various time ranges. It is a nested json object that contains forecast data for impressions, clicks, and adSpend.
The estimates objects are detailed below in a separate table following this one.		json
detailsDetails of the response.
Values:
  • REACH_ESTIMATE_SUCCESS
  • REACH_ESTIMATE_FAILURE
json

estimates Objects:

each metrics ( impressions, clicks, and adSpend ) is structured as follows:

ElementsDescriptionType
dailyEstimated metric values per dayjson
30daysEstimated metric values for 30 daysjson
lifetimeEstimated metric values for the ad group's full lifetimejson

each sub-object (daily, 30days, lifetime) contains:

ElementsDescriptionType
minValueLower bound of the estimated metric rangeint
maxValueUpper bound of the estimated metric rangeint

Delivery Estimate Success Response

{ "code": "success", "forecastId": "567", "estimates": { "impressions": { "daily": { "minValue": 1, "maxValue": 2 }, "30days": { "minValue": 1, "maxValue": 2 }, "lifetime": { "minValue": 1, "maxValue": 2 } }, "clicks": { "daily": { "minValue": 3, "maxValue": 4 }, "30days": { "minValue": 1, "maxValue": 2 }, "lifetime": { "minValue": 3, "maxValue": 4 } }, "adSpend": { "daily": { "minValue": 5, "maxValue": 7 }, "30days": { "minValue": 2, "maxValue": 3 }, "lifetime": { "minValue": 5, "maxValue": 7 } } }, "details": [ "DELIVERY_ESTIMATE_SUCCESS" ]
}

Delivery Estimate Failure Response

{ "code": "failure", "details": [ "FAILURE_FETCHING_DELIVERY_ESTIMATE" ]
}

Updated 2 days ago