Create Campaign Recommendations Request
Campaign Recommendations endpoint will provide recommendations on eligible campaigns for a particular recommendationType. Currently, we support Target ROAS recommendation type.
URL: POST /api/v2/snapshot/recommendations
Request Parameters
| Parameter | Description | Type | Required | Possible Values |
|---|---|---|---|---|
| advertiserId | The ID of the advertiser | integer | Y | Unique numeric identifier for the advertiser. This is the advertising account id. This parameter can take only one advertiser Id for each snapshot report request. |
| recommendationType | The type of the recommendation required | string | Y | Values of recommendation type: targetROASoutOfBudget |
| format | Choose the format type for your snapshot | string | Y | Types of formats: gzip. Note: gzip allows decompression while file is being transferred over the network, hence it is a faster and simpler way to download the reports |
| reportMetrics | List of report metrics to be displayed for the selected recommendation report | array | Y | Please see the following tables for possible report metrics |
TROAS Metrics
| Element | Description | Data Type | Required | Possible Values |
|---|---|---|---|---|
| reportDate | The snapshot date for the report. | date | Y | The date should be in “yyyy-MM-dd” format. This parameter can take only one report date for the last 90 days for each snapshot report request. |
| campaignId | The Id of the campaign | Integer | Y | Unique ID for the given campaign. |
| recommendedTargetROAS | Recommended Target ROAS value | float | Y | The recommendation value can be between 1 and 31.27. |
| troasRecommendedDailyBudget | The recommended daily budget to set for the campaign to help maximize sales at the suggested ROAS target | float | N | We recommend passing this value to obtain target ROAS budget |
| troasIncrementalSalesLower | The lower range of the potential incremental sales we predict your campaign can generate if you update your campaigns with our recommendation following the learning phase | float | N | We recommend passing this value |
| troasIncrementalSalesUpper | The upper range of the potential incremental sales we predict your campaign can generate if you update your campaigns with our recommendation following the learning phase | float | N | We recommend passing this value |
| troasRecommendationId | Recommendation id for the target ROAS recommendation | string | N | We highly recommend passing troasRecommendationId in the report metrics |
Out of Budget Metrics
| Element | Description | Data Type | Required | Possible Values |
|---|---|---|---|---|
| startDate | The start date for the report. | date | Y | The date should be in “yyyy-MM-dd” format. |
| endDate | The end date for the report | date | Y | The date should be in “yyyy-MM-dd” format. |
| campaignId | The Id of the campaign | integer | Y | Unique ID for the given campaign. |
| budgetType | The budget type of the campaign | string | N | dailytotalboth |
| missedClicksLower | This field provides cumulative lower range of missed clicks over last 7 days for a campaign which went out of budget (OOB) for T-1 time | integer | N | |
| missedClicksUpper | This field provides cumulative upper range of missed clicks over last 7 days for a campaign which went out of budget (OOB) for T-1 time | integer | N | |
| missedImpressionsLower | This field will provide cumulative lower range of missed impressions over last 7 days for a campaign which went out of budget (OOB) for T-1 time | integer | N | |
| missedImpressionUpper | This field will provide cumulative upper range of missed impressions over last 7 days for a campaign which went out of budget (OOB) for T-1 time | integer | N | |
| avgCapOutTime | The average cap out time is the average time for which the campaign went out of budget in the last 7 days. This value is represented in military time e.g. 1000 refers to 10 AM. | integer | N |
Notes on the Out of Budget Recommendations Report
This report offers insights on aggregated missed opportunities (clicks and impressions) for last 7 days for campaign(s) which went out of budget for T-1 time and provides latest daily and/or total budget recommendations so that you can update the budget recommendations to avoid campaign(s) going Out of Budget (OOB).
- The
outOfBudgetreport provides cumulative missed impressions and clicks for last 7 days for any campaign(s) which went out of budget (OOB) for T-1 time for an advertiser account. This means if you request a report today and if the campaign went OOB yesterday, you would see cumulative missed impressions and clicks for last 7 days.
Note:- Significance of T-1 time : If you request a report today, you will receive recommendations for any campaign which went out of budget yesterday.
- The daily and/or total budget recommendation will be latest and not cumulative for last 7 days.
- If the campaign(s) did not go OOB for T-1 time and does not have any recommendations, the report will not show the entry for those campaign(s). This means if you request a report today, those campaigns that didn’t go OOB yesterday, will not be listed in the report.
- For this report,
startDate,endDatecampaignIdare mandatory parameters in thereportMetricsobject. - The
outOfBudgetreport will only provide latest daily and/or total budget recommendations and not cumulative for the last 7 days period for any campaign(s) which went OOB for T-1 time for an advertiser account. This means if you request a report today and if the campaign went OOB yesterday, you would see the latest daily and/or total budget recommendations. Use these budget recommendations to update your campaign(s) to ensure the campaign(s) do not go out of budget. - If the campaign has only a daily budget set, the total budget recommendation will be null if requested in the report metrics. Likewise, if the campaign has only a total budget set, the daily budget recommendation will be null if requested.
- This report will also provide average cap out time, such as the average time (in 24-hour time format) in the event of the campaign going OOB in last 7 days as applicable.
- This report type is advertiser account based and will list missed opportunities and latest budget recommendations for all campaign(s) belonging to the advertiser account which went OOB for T-1 time.
- The lookback window for this report is 7 days.
- For any reason, if missed clicks and impressions are missing whereas budget recommendations exist, then missed clicks and impressions will be null.
- For any reason, if average cap out time is missing whereas budget recommendations exist, then average cap out time will be null.
- Our model calculates the missed opportunities and budget recommendations once every 24 hours for OOB campaigns. This feature is in beta phase but available to be used for all advertising accounts while we continue to iterate on our model.
Sample Request
curl -X POST \ 'https://developer.api.stg.walmart.com/api-proxy/service/WPA/Api/v1/api/v2/snapshot/recommendations' \ --header 'Authorization: Bearer <auth_token>' \ --header 'accept: application/json' \
--header 'WM_SEC.AUTH_SIGNATURE: ***********' \
--header 'WM_SEC.KEY_VERSION: 1' \ --header 'WM_CONSUMER.ID: adfwe-v23-faasd2r-afs-asdfqeff' \
--header 'WM_CONSUMER.intimestamp: 1565309779' \
--header 'Content-Type: application/json' \ --data '{ "advertiserId": 600001, "recommendationType": "targetROAS", "format": "gzip", "reportMetrics": [ "reportDate", "campaignId", "recommendedTargetROAS" ] }' Sample Request 2
curl -X POST \ 'https://developer.api.stg.walmart.com/api-proxy/service/WPA/Api/v1/api/v2/snapshot/recommendations' \ --header 'Authorization: Bearer <auth_token>' \ --header 'accept: application/json' \
--header 'WM_SEC.AUTH_SIGNATURE: ***********' \
--header 'WM_SEC.KEY_VERSION: 1' \ --header 'WM_CONSUMER.ID: adfwe-v23-faasd2r-afs-asdfqeff' \
--header 'WM_CONSUMER.intimestamp: 1565309779' \
--header 'Content-Type: application/json' \ --data '{ "advertiserId": 600001, "recommendationType": "targetROAS", "format": "gzip", "reportMetrics": [ "reportDate", "campaignId", "recommendedTargetROAS", "troasRecommendationId", "troasRecommendedDailyBudget", "troasIncrementalSalesLower", "troasIncrementalSalesUpper" ] }'
Sample Request 3
curl -X POST \ 'https://developer.api.stg.walmart.com/api-proxy/service/WPA/Api/v1/api/v2/snapshot/recommendations' \ --header 'Authorization: Bearer <auth_token>' \ --header 'accept: application/json' \
--header 'WM_SEC.AUTH_SIGNATURE: ***********' \
--header 'WM_SEC.KEY_VERSION: 1' \ --header 'WM_CONSUMER.ID: adfwe-v23-faasd2r-afs-asdfqeff' \
--header 'WM_CONSUMER.intimestamp: 1565309779' \
--header 'Content-Type: application/json' \ --data '{ "advertiserId": 600001, "recommendationType": "outOfBudget", "format": "gzip", "reportMetrics": [ "startDate", "endDate", "campaignId", "budgetType", "missedClicksLower", "missedClicksUpper", "missedImpressionsLower", "missedImpressionsUpper", "avgCapOutTime" ] }'
Updated 17 days ago