Request Delivery Estimate V2
Use this API to request delivery estimates or winning impressions forecast for a given ad group
- 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.
- 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.
Request Parameters
| Parameters | Notes | Type | Required | Possible Values |
|---|---|---|---|---|
| advertiserId | ID of advertiser | integer | Y | Unique numeric identifier |
| campaignId | ID of the campaign containing the ad group | integer | Y | Valid campaign ID |
| adGroupId | ID the ad group to forecast | integer | N | Valid ad group ID |
| metric | impressions - The range & point estimate of total winning impressions aggregated over the entire query duration. clicks -The range & point estimate of total clicks aggregated over the entire query duration. adSpend- The range & point estimate of adspend aggregated over the entire query duration. orders-The range & point estimate of total sales aggregated over the entire query duration. cpc - The range & point estimate of cpc aggregated over the entire query duration. cps - The range & point estimate of cps aggregated over the entire query duration. sales - The estimated range of attributed sales in USD for the requested ad-group configuration and forecast timeframe. | array | Y |
|
| timeFrames | Specifies the timeframes for which forecasts should be returned. If not provided, forecasts for all available timeframes will be returned. | array | N | Values: ifetime |
| startDate | Simulated start date for ad group scheduling | string | Conditional* | Required if not set at ad group level. Date must follow this format: Note:
Kindly take these behaviors into consideration when assigning a value to startDate in your request. |
| endDate | Simulated end date for ad group scheduling. For ad groups that run indefinitely, use the value: endDate = ‘9999-12-30T00:00:00Z’ | string | Conditional* | Required if not set at ad group level. Note:
Kindly take these behaviors into consideration when assigning a value to startDate in your request. |
| targeting | Defines the audience, contextual, keyword, and geographic targeting criteria for an ad group. This object supports both. Supports both expression-based and flattened targeting structure. View more details about the targeting object and its schema structures from the Ad group documentation here You must choose one structure; mixing flat and expression-based schemas in a single payload is not supported. | object | Conditional* | |
| maxBid | Simulated maximum bid value for the ad group | double | Conditional* | Value of max bid. It Must be >=$0.01 |
| baseBid | Simulated starting bid for the ad group | double | Conditional* | Value of base bid. Value of base bid. It Must be >=$0.01 |
| frequencyCapDay | The number of times the ad from specific ad group should be shown to the same user in a day | integer | N | Integer values between 1 and 511 |
| frequencyCapWeek | The number of times the ad from specific ad group should be shown to the same user in a week | integer | N | Integer values between 3 and 511 |
| frequencyCapMonth | The number of times the ad from specific ad group should be shown to the same user in a month | integer | N | Integer values between 5 and 511 |
| dailyBudget | Simulated daily budget of the ad group | double | Conditional* | The value of daily budget should at least be $0.01 |
| totalBudget | Simulated total budget of ad group | double | Conditional* | The value of total budget should at least be $0.01 |
| deliverySpeed | Determines pacing of ad delivery. Note: frontloaded pacing is not supported if budgetType is daily. | string | Conditional* | Values:
|
*Conditional - required if not configured for the adGroupId
Note: If adGroupId is not provided, startDate, endDate, targeting, dailyBudget or totalBudget, maxBid should be mandatorily passed and the forecast returned should be based on the specified values of startDate, endDate, targeting, dailyBudget or totalBudget, maxBid .
- 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": { "runOfSite": true, "geoTargets": { "include": [ { "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"] }' Sample Request - Get impression, clicks ,ad spend and orders forecasts for an ad group without the adGroupId 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, "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, "frequencyCapDay": 50, "frequencyCapWeek": 50, "frequencyCapMonth": 50, "dailyBudget": 100, "deliverySpeed": "evenly" }' Response
| Element | Description | Required | Type |
|---|---|---|---|
| code | The response code can have following values:
| Y | string |
| forecastId | Unique identifier for the forecast request. forecastId is returned for every successful response | N | string |
| estimates | Contains forecasted metrics over various time ranges. It is a nested json object that contains forecast data for impressions, clicks, orders ,adSpend, cpc and cpsThe estimates objects are detailed below in a separate table following this one. | object | |
| details | Details of the response. Values:
| array | |
| errors | details when there is partial response | array |
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:
| Elements | Description | Type |
|---|---|---|
| daily | Estimated metric values per day | object |
| 30days | Estimated metric values for 30 days | object |
| lifetime | Estimated metric values for the ad group's full lifetime | object |
Estimate range Object: Each time-range object (daily, 30days, lifetime) contains the estimated range values described below :
| Elements | Description | Type |
|---|---|---|
| minValue | Lower bound of the estimated metric range | int |
| maxValue | Upper bound of the estimated metric range Note: This field is omitted when there is no defined upper bound for the estimate | int |
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" ], "message": "string",
"errors": [ { "field": "string", "errorType": "string", "description": "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" ], "message": "string",
"errors": [ { "field": "string", "errorType": "string", "description": "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" ], "message": "string",
"errors": [ { "field": "string", "errorType": "string", "description": "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" ], "message": "string",
"errors": [ { "field": "string", "errorType": "string", "description": "string" } ]
}Delivery Estimate Success Response - Get impression, clicks ,ad spend and orders forecasts for an ad group without the adGroupId 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 without the adGroupId with updated values for schedule, targeting, bid, budget and frequency caps(Expression based Targeting Structure)
{ "code": "failure", "details": [ "string" ], "message": "string",
"errors": [ { "field": "string", "errorType": "string", "description": "string" } ]
}Failure Response
{ "code": "failure", "details": [ "string" ], "message": "string",
"errors": [ { "field": "string", "errorType": "string", "description": "string" } ]
}Updated 2 days ago
Did this page help you?