HomeGuidesAPI ReferenceRelease Notes
Guides

Create New Ad Group

📘

URL: POST/api/v1/adGroups

Note:

  • This API supports batch operations with a max batch size of 10. For bulk operation, the advertiserId must be the same across all requests in the payload
  • Creating multiple ad groups with different targeting types is supported in Bulk. For example: A single bulk payload can include one ad group Create request with keyword targeting and another ad group create request with contextual targeting
  • 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

Request Parameters

ParametersNotesTypeRequiredPossible Values
campaignIdID of the campaign this ad group belongs tointegerYUnique numeric identifier
advertiserIdID of advertiser for whom the ad group(s) should be createdintegerYUnique numeric identifier
nameThe name of the ad groupstringYRelevant string value representing the ad group
startDatedate on which the ad group is set to go live
Note: startDate must be set either at campaign or ad group level		date. ISO 8601 timezoneConditional. This field is required only if it is not set at campaign level. Cannot be changed to campaign level laterDate should be in 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 scheduling start and end dates.
endDateThe date when ad group ends
Note: endDate must be set either at campaign or ad group level		date. ISO 8601 timezoneConditional.
This field is required only if it is not set at campaign level. Cannot be changed to campaign level later		Date should be in format:
yyyy-MM-dd'T'HH:mm:ss.SSSXXX

To run campaign indefinitely, set its value as "9999-12-30T00:00:00Z"

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 scheduling start and end dates.
rateTyperate type refers to the pricing structurestringNcpm
budgetTypeThe type of budget allocation you want to choose for the ad group

Note: it must be set either at campaign or ad group level
Ad groups scheduled to run indefinitely must use a daily budget		stringConditional.
This field is required only if it is not set at campaign level. Cannot be changed to campaign level later		Values:

- daily
- total
dailyBudgetDaily budget of ad group
_Note:
• Daily budget cannot exceed your total budget amount
• Unspent budget will be rolled over to the next day
• Up to 20% of the unspent budget will be rolled over to the following day
• It must be set either at Campaign or ad group level
• Ad groups scheduled to run indefinitely must use a daily budget		doubleConditional.
This field is required only if:
-It is not
set at campaign level. Cannot be changed to campaign level later

-budgetType is set to be daily		The value of daily budget should at least be $0.01
totalBudgetTotal budget of ad group
Note: it must be set either at campaign or ad group level		doubleConditional.This field is required only if:
-It is not
set at campaign level. Cannot be changed to campaign level later

-budgetType is set to be total		The value of total budget should at least be $0.01
deliverySpeedDetermines pacing of ad delivery
Note: it must be set either at campaign or ad group level		string Conditional.This field is required only if it is not set at campaign level. Cannot be changed to campaign level laterValues:
• frontloaded
• evenly
Note: frontloaded pacing is not supported if budgetType is daily
creativeRotationModeSpecifies the rotation strategy for creatives within an ad group during delivery.

Creatives can either be automatically rotated and prioritized based on performance (OPTIMIZE_PERFORMANCE), or distributed evenly with equal weight (ROTATE_EVENLY)		stringNEnum Values:

•OPTIMIZE_PERFORMANCE (Default value)
•ROTATE_EVENLY
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
baseBidStarting bid for the ad groupdoubleNValue of base bid
maxBidMax bid value for the ad groupdoubleNValue of max bid
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: is used for Country, State, City or DMA targets.
      integer data type
    • zipCode: is used for zip code targeting. We only support ZIP codes within the USA currently, string data type

Note:
1. In an ad group, geo targeting can be set to one of:
  • Country
  • State, City
  • DMA
  • Zip code
Refer to the sample requests for creating an Ad Group with ROS to see how zip codes are used in geo-targeting.

2. You cannot combine different geo-targeting types within a single ad group

3. If Geo targeting is not specified, the default Country (US) level targeting will be applied

4. IDs with isDisabled = true from POST/api/v1/targeting/list cannot be used for targeting		N

Notes:

  • startDate >= today’s date
  • startDate <= endDate
  • total and daily budget should be >= max bid
  • 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

Headers

Header NameDescriptionRequiredValues
AuthorizationThe token will provide you the access to the API. It is same for all advertisers you access through the APIYPlease utilize the generated auth_token shared with you at the time of partner onboarding from the Getting Started Guide. This key can be repurposed for SP API access as well.
WM_CONSUMER.IDWe will provide you the consumer ID to access the API. It is same for all advertisers you access through the API.YPlease use the generated ConsumerId shared with you at the time of partner onboarding. Refer to the Getting Started Guide for further explanation on this
WM_SEC.AUTH_SIGNATUREAuth signature as an API keyYUse the signature generator code from Getting Started Guide to generate this value
WM_CONSUMER.intimestampTimestamp for which the auth signature is generated. Use Unix epoch format for the timestampYUse the signature generator code (Getting Started Guide) to generate this value
WM_SEC.KEY_VERSIONWe will provide you with the KEY VERSION to access the API. It is same for all advertisers you access through the APIY1

Sample Request: Create Ad Group with Keyword Targeting

curl -X POST \
'https://developer.api.us.stg.walmart.com/api-proxy/service/display/api/v1/api/v1/adGroups' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer <auth_token>'
--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' --data '[ {
"campaignId": 1,
"advertiserId": 1,
"name": name1,
"startDate": "2023-12-01T12:00:00Z", "endDate": "2023-12-09T12:00:00Z",
"rateType" : "cpm",
"budgetType" : "daily",
"dailyBudget": 500, "totalBudget": 5000, "deliverySpeed" : "evenly", "creativeRotationMode": "OPTIMIZE_PERFORMANCE", "frequencyCapDay" : 0, "frequencyCapWeek" : 0, "frequencyCapMonth" : 0,
"baseBid" : 0.0,
"maxBid" : 0.0, "targeting" : { "and": [ { "keywords": [ { "keywordText": "test-keyword-1", "matchType": "broad" }, { "keywordText": "test-keyword-2", "matchType": "exact" } ], "not": [ { "keywords": [ { "keywordText": "test-keyword-negative", "matchType": "exact" } ] } ] }, { "geoTargets": [ { "id": 123 }, { "id": 234 }, { "id": 235 } ] } ] } }
]'

Sample Request: Create Ad Group with Contextual Targeting

curl -X POST \
'https://developer.api.us.stg.walmart.com/api-proxy/service/display/api/v1/api/v1/adGroups' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer <auth_token>'
--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' --data ' [ {
"campaignId": 1,
"advertiserId": 1,
"name": name1,
"startDate": "2023-12-01T12:00:00Z", "endDate": "2023-12-09T12:00:00Z",
"rateType" : "cpm",
"budgetType" : "daily",
"dailyBudget": 500,
"totalBudget": 5000,
"deliverySpeed" : "evenly",
"creativeRotationMode":"OPTIMIZE_PERFORMANCE", "frequencyCapDay" : 0, "frequencyCapWeek" : 0, "frequencyCapMonth" : 0,
"baseBid" : 0.0,
"maxBid" : 0.0, "targeting" : { "and": [ { "contextual": [ { "id": 3452, "reach": "tier_2" }, { "id": 2343, "reach": "tier_3" } ]
}, { "geoTargets": [ { "id": 123 }, { "id": 234 }, { "id": 235 } ] } ] } }
]'

Sample Request: Create Ad Group with Behavioral Targeting

curl -X POST \
'https://developer.api.us.stg.walmart.com/api-proxy/service/display/api/v1/api/v1/adGroups' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer <auth_token>'
--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'
--data ' [ {
"campaignId": 1,
"advertiserId": 1,
"name": name1,
"startDate": "2023-12-01T12:00:00Z", "endDate": "2023-12-09T12:00:00Z", "rateType" : "cpm",
"budgetType" : "daily",
"dailyBudget": 500,
"totalBudget": 5000,
"deliverySpeed" : "evenly",
"creativeRotationMode": OPTIMIZE_PERFORMANCE", "frequencyCapDay" : 0,
"frequencyCapWeek" : 0,
"frequencyCapMonth" : 0,
"baseBid" : 0.0,
"maxBid" : 0.0, "targeting" : { "and": [ { "behavioral": [ { "audienceType": "retail", "attribute": "historical", "id": 134 }, { "audienceType": "retail", "attribute": "historical", "id": 243234 } ]
}, { "geoTargets": [ { "id": 123 }, { "id": 134 }, { "id": 1233 } ] } ] } }
]'

Sample Request: Create Ad Group with ROS

curl -X POST \
'https://developer.api.us.stg.walmart.com/api-proxy/service/display/api/v1/api/v1/adGroups' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer <auth_token>'
--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' --data ' [ {
"campaignId": 1,
"advertiserId": 1,
"name": name1,
"startDate": "2023-12-01T12:00:00Z", "endDate": "2023-12-09T12:00:00Z",
"rateType" : "cpm",
"budgetType" : "daily",
"dailyBudget": 500,
"totalBudget": 5000,
"deliverySpeed" : "evenly",
"creativeRotationMode": OPTIMIZE_PERFORMANCE", "frequencyCapDay" : 0, "frequencyCapWeek" : 0, "frequencyCapMonth" : 0,
"baseBid" : 0.0,
"maxBid" : 0.0, "targeting" : { "and": [ { "runOfSite": true }, { "geoTargets": [ { "zipCode":"35004" } ] } ] } }
]'

Sample Request (Batch Operation)

curl -X POST \
'https://developer.api.us.stg.walmart.com/api-proxy/service/display/api/v1/api/v1/adGroups' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer <auth_token>'
--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' --data '[ {
"campaignId": 1,
"advertiserId": 1,
"name": "string",
"startDate": "string",
"endDate": "string",
"rateType" : "string",
"budgetType" : "string",
"dailyBudget": 0.0, "totalBudget": 0.0, "deliverySpeed" : "string", "deliverySpeed" : "string", "creativeRotationMode": "OPTIMIZE_PERFORMANCE", "frequencyCapDay" : 0,
"frequencyCapWeek" : 0,
"frequencyCapMonth" : 0,
"baseBid" : 0.0,
"maxBid" : 0.0, "targeting" : { "and": [ { "keywords": [ { "keywordText": "test-keyword-1", "matchType": "broad" }, { "keywordText": "test-keyword-2", "matchType": "exact" } ], "not": [ { "keywords": [ { "keywordText": "test-keyword-negative", "matchType": "broad" } ] } ] }, { "geoTargets": [ { "id": 123 }, { "id": 234 }, { "id": 235 } ] } ] } }, { "campaignId": 1,
"advertiserId": 1,
"name": string1,
"startDate": "string", "endDate": "string",
"rateType" : "string",
"budgetType" : "string",
"dailyBudget": 0.0,
"totalBudget": 0.0,
"deliverySpeed" : "string",
"creativeRotationMode": "string", "frequencyCapDay" : 0, "frequencyCapWeek" : 0, "frequencyCapMonth" : 0,
"baseBid" : 0.0,
"maxBid" : 0.0, "targeting" : { "and": [ { "contextual": [ { "id": 3452, "reach": "tier_2" }, { "id": 2343, "reach": "tier_3" } ] }, { "geoTargets": [ { "zipCode":"35004" } ] } ] } } ]'

Response

ElementDescriptionType
codeThe response code can have following values:
  • success
  • failure

Click here for more information about Status Codes and Errors		string
detailsDetails will populate success or error message depending upon value of codestring
nameName of the campaignstring
adGroupIdID of the Ad Group. This will be returned only when code=successinteger
campaignIdID of the campaign. This will be returned only when code=successinteger

Sample Response


[ { "code": "success", "details": "string", "name": "string1", "campaignId": 1, "adGroupId": 1234 }
]

Sample Response (Batch Operation)


[ { "code": "success", "details": "string", "name": "string1", "campaignId": 1, "adGroupId": 1234 }, { "code": "failure", "details": ["string"], "name": "string1", "campaignId": 1 } ]

Updated about 8 hours ago