HomeGuidesAPI ReferenceRelease Notes
Guides

Request Delivery Estimate V1

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

👉

What It Does:

  • Predicts delivery performance of an ad group using its configured schedule, targeting, budget, and bid.
    Allows developers to simulate changes to ad group configuration by overriding fields in the request payload.
  • Does not modify any stored ad group or campaign data — simulation is used solely for forecasting purposes.
  • To return a valid delivery estimate, the following ad group-level attributes must be available either in the stored ad group OR passed in the request: schedule, budget, bid and targeting. If any of the four are missing in the ad group and not provided in the request payload, the API returns an error.

👉

Simulation (“What-If” analysis) support:

  • You can override ad group-level startDate, endDate, baseBid,maxBid, frequencyCap, dailyBudget, totalBudget, deliverySpeed and targeting in the request body to simulate changes without modifying the actual ad group.
  • Campaign-level schedules, budget & deliverySpeed that cascade to ad groups cannot yet be simulated in this API. If budget, schedule and deliverySpeed are set at the campaign level, the API will disregard these values if passed, and the forecast provided will use the original campaign values instead.
  • All overrides are non-persistent. This API does not modify stored campaign or ad group data.

📘

URL: POST/api/v1/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

Request Parameters

ParametersNotesTypeRequiredPossible Values
advertiserIdID of advertiser integerYUnique numeric identifier
campaignIdID of the campaignintegerYUnique numeric identifier
adGroupIdID the ad groupintegerYUnique numeric identifier
metricThe specified metric you are requesting an estimate for.

Note: “impressions” is currently the only supported metric.		arrayYValue:
impressions
startDateDate when the ad group is set to go live.

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

here

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

Note: All date and time values are internally converted to Eastern Time (ET) for processing.

All timestamps must be provided in ISO 8601 format. Timestamps are normalized to the start of the hour in Eastern Time (ET)—this means any minutes and seconds will be truncated.

Please account for this when requesting for forecasts.
endDateThe date when ad group ends. 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

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

Note: All date and time values are internally converted to Eastern Time (ET) for processing.

All timestamps must be provided in ISO 8601 format. Timestamps are normalized to the start of the hour in Eastern Time (ET)—this means any minutes and seconds will be truncated.
Additionally, the end date must be set to a time after 12:00 PM ET

Please account for this when requesting for forecasts.
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
maxBidMaximum 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
baseBidStarting bid for the ad groupdoubleNValue of base bid
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
dailyBudgetDaily 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
totalBudgetTotal 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

doubleN• frontloaded
• evenly

Sample Request

curl --location --request POST 'https://developer.api.us.walmart.com/api-proxy/service/display/api/v1/api/v1/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"], "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

Click here for more information about Status Codes and Errors		string
metricThe metric that was specified in the request body; i.e., IMPRESSIONSstring
minValueMinimum number of the specified metric for the delivery estimate.integer
maxValueMaximum number of the specified metric for the delivery estimate.
Note:
  • A null value for maxValue indicates that the maximum value is either undefined or unbound.
  • This field is omitted when there is no defined upper bound for the estimate
integer
detailsDetails of the request statusstring

Sample Response

[ { "code": "success", "metric": "IMPRESSIONS", "minValue": 7000, "maxValue": 14000, "details": [ "IMPRESSION_ESTIMATE_SUCCESS" ] }
]

Updated about 16 hours ago