Request Delivery Estimate V2

👉

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/v2/deliveryEstimate

Request Parameters

*Conditional - required if not configured for the adGroupId

👉

Rules

• 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: startDate, endDate, dailyBudget or totalBudget, maxBid and targeting. If any of these are missing in the ad group and not provided in the request payload, the API returns an error.
• If the following request parameters are set at the campaign level: startDate, endDate, dailyBudget, totalBudget, deliverySpeed, the values for these parameters in the request payload 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, dailyBudget, totalBudget, deliverySpeed, baseBid, maxBid, frequencyCapDay, frequencyCapWeek, frequencyCapMonth, targeting, the values provided for these parameters in the request payload override the original values set at ad group level and are used in the forecast response instead
• To get orders forecast, the campaign should have a built featured itemset associated to it
• 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.
• You must set all of budgetType, dailyBudget, totalBudget, startDate, endDate, and deliverySpeed parameters at same level i.e. either at campaign level or ad group level, not both
• If startDate, endDate, budgetType, dailyBudget, totalBudget, deliverySpeed are omitted, they must be defined at the ad group level
• You can only set either dailyBudget or totalBudget
• To set daily budget, you must choose value of budgetType as “daily” and then define dailyBudget.
• To set total budget, you must choose value of budgetType as “total” and then define totalBudget.
• Budget, Schedule and Delivery speed must be set either at campaign or ad group level
• If timeFrames not provided in the request, API returns delivery estimate for all the three timeframes
• For partial Response in orders data , API will return 206 response code
• Only one of flat or expression-based schemas can be be provided for targeting object in a single payload

Sample Request - Get impression, clicks ,ad spend and orders forecasts for an ad group with updated values for schedule, targeting, bid, budget and frequency caps (Expression based Targeting Structure)

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": 1, "campaignId": 9, "adGroupId": 2, "metric": [ "impressions","clicks","adSpend","orders" ], "timeframes":["daily","30days","lifetime"], "startDate": "2024-06-27T00:00:00Z", "endDate": "2024-12-30T23:59:59Z", "targeting": { "and": [ { "runOfSite": true }, { "geoTargets": [ { "id": 1 } ] } ] }, "maxBid": 10, "baseBid": 2, "frequencyCapDay": 50, "frequencyCapWeek": 50, "frequencyCapMonth": 50, "dailyBudget": 100, "deliverySpeed": "evenly"
}' 

Sample Request - Get impression, clicks ,ad spend and orders forecasts for an ad group with updated values for schedule, targeting, bid, budget and frequency caps (Flattened Targeting Structure)

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": 1, "campaignId": 9, "adGroupId": 2, "metric": [ "impressions","clicks","adSpend","orders" ], "timeframes":["daily","30days","lifetime"], "startDate": "2024-06-27T00:00:00Z", "endDate": "2024-12-30T23:59:59Z", "targeting": { "and": [ { "runOfSite": true }, { "geoTargets": [ { "id": 1 } ] } ] }, "maxBid": 10, "baseBid": 2, "frequencyCapDay": 50, "frequencyCapWeek": 50, "frequencyCapMonth": 50, "dailyBudget": 100, "deliverySpeed": "evenly"
}' 

Sample Request - Get impression, clicks ,ad spend and orders forecasts for an ad group in a campaign that does not have a featured itemset associated

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": 1, "campaignId": 9, "adGroupId": 2, "metric": [ "impressions","clicks","adSpend","orders" ], "timeframes":["daily","30days","lifetime"] }' 

Sample Request - Get impression, clicks ,ad spend and orders, cpc,cps forecasts for an ad group in a campaign that does not have a featured itemset associated

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": 1, "campaignId": 9, "adGroupId": 2, "metric": [ "impressions","clicks","adSpend","orders",,"cpc","cps" ], "timeframes":["daily","30days","lifetime"] }' 

Response

estimates Objects:

The estimates object contains forecasted metrics across multiple time ranges. Each supported metric (for example, impressions, clicks) is represented as a nested object with estimated ranges. Each metric object may include one or more time-range sub-objects.

Object structure:

"estimates": { "<metric>": { "daily": { ... }, "30days": { ... }, "lifetime": { ... } }
}

Time-Range Sub-Objects: Each metric can contain the following optional sub-objects:

Estimate range Object: Each time-range object (daily, 30days, lifetime) contains the estimated range values described below :

Delivery Estimate Success Response - Get impression, clicks ,ad spend and orders forecasts for an ad group with updated values for schedule, targeting, bid, budget and frequency caps (Expression based Targeting Structure)

{ "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 } }, "orders": { "daily": { "minValue": 100, "maxValue": 400 }, "30days": { "minValue": 6200, "maxValue": 7900 }, "lifetime": { "minValue": 42000, "maxValue": 50000 } } }, "details": [ "DELIVERY_ESTIMATE_SUCCESS" ]
} 

Delivery Estimate Failure Response - Get impression, clicks ,ad spend and orders forecasts for an ad group with updated values for schedule, targeting, bid, budget and frequency caps (Expression based Targeting Structure)

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

Delivery Estimate Success Response - Get impression, clicks ,ad spend and orders forecasts for an ad group with updated values for schedule, targeting, bid, budget and frequency caps (Flattened Targeting Structure)

{ "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 } }, "orders": { "daily": { "minValue": 100, "maxValue": 400 }, "30days": { "minValue": 6200, "maxValue": 7900 }, "lifetime": { "minValue": 42000, "maxValue": 50000 } } }, "details": [ "DELIVERY_ESTIMATE_SUCCESS" ]
} 

Delivery Estimate Failure Response -Get impression, clicks ,ad spend and orders forecasts for an ad group with updated values for schedule, targeting, bid, budget and frequency caps(Flattened Targeting Structure)

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

Delivery Estimate Partial Success Response - Get impression, clicks ,ad spend and orders forecasts for an ad group in a campaign that does not have a featured itemset associated

206- partial success { "code": "partial_response", "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 } }, "orders": { "daily": { "minValue": -1, "maxValue": -1 }, "30days": { "minValue": -1, "maxValue": -1 }, "lifetime": { "minValue": -1, "maxValue": -1 } } }, "errors": [ "ITEMSETID_IS_REQUIRED_FOR_ORDERS_METRICS" ]
}

Delivery Estimate Failure Response - Get impression, clicks ,ad spend and orders forecasts for an ad group in a campaign that does not have a featured itemset associated

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

Delivery Estimate Success Response - Get impression, clicks ,ad spend and orders, cpc,cps forecasts for an ad group in a campaign that does not have a featured itemset associated

{ "code": "partial_response", "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 } }, "orders": { "daily": { "minValue": -1, "maxValue": -1 }, "30days": { "minValue": -1, "maxValue": -1 }, "lifetime": { "minValue": -1, "maxValue": -1 } }, "cpc": { "daily": { "minValue": 5, "maxValue": 16 }, "30days": { "minValue": 5, "maxValue": 16 }, "lifetime": { "minValue": 5, "maxValue": 16 } }, "cps": { "daily": { "minValue": 5, "maxValue": 16 }, "30days": { "minValue": 5, "maxValue": 16 }, "lifetime": { "minValue": 5, "maxValue": 16 } } }, "errors": [ "ITEMSETID_IS_REQUIRED_FOR_ORDERS_METRICS" ]
}

Delivery Estimate Failure Response - Get impression, clicks ,ad spend and orders, cpc,cps forecasts for an ad group in a campaign that does not have a featured itemset associated

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