Skip to content

Ad Groups

Overview

An ‘ad group’ is a subgroup within a campaign which can be used to group items with similar keywords or goals. This helps streamline the campaign creation process and makes it easier to optimize campaigns. Keeping ad groups small and manageable helps advertisers maintain a competitive edge and avoid competing against their own campaigns.

Usage:

  • To create new Ad Groups within a campaign for an advertiser
  • To retrieve all the ad group(s) for a specific campaign
  • To enable, disable or delete existing ad group

Limitations:

  • A maximum of 50 entities can be created/updated in a single POST/PUT batch request
  • Limit on length of ad group name is 255 characters
  • Limit on number of items in an ad group is 2000
  • Limit on number of “keyword-match type” combinations in an ad group is 1000
  • Similar keyword with different match types will be counted as separate entries. For example, laptop-exact match and laptop-broad match will count as two entries.
  • All existing ad groups with more than 2000 items and/or more than 1000 keyword- match type combinations will continue to function normally
  • There is no limit on number of ad groups in a campaign
  • Limit on number of ad groups that an advertiser can create per advertiser account is, 15000
  • For Sponsored Brands (also known as Search Brand Amplifier or SBA) campaigns, only one ad group is allowed per campaign

To understand details about ‘Request Header' or 'Authorization’, please refer to the Authorization Guide

Create Ad Group

Description: Create new ad groups within a campaign for an advertiser

End Point: /api/v1/adGroups

HTTP Method: POST

Body Parameters

Parameter Description Type Required Possible Values
name The name of the campaign String N The campaign name should be unique and corresponds to the campaign ID
status Status of the campaign String N Possible values:
  • enabled: Use this status to enable an ad group for a campaign.
  • disabled: Use this status to disable an ad group for a campaign.
campaignId ID of the campaign to which this ad group belongs Integer Y Unique numeric identifier

Sample Request

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
curl --location   
'https://developer.api.us.stg.walmart.com/api-proxy/service/sp/api-sams/v1/api/v1/adGroups
--header 'Authorization: Bearer ***********' 
--header 'Content-Type: application/json' 
--header 'wm_consumer.id: **************'  
--header 'wm_sec.key_version: 2'  
--header 'wm_sec.auth_signature: **************' 
--header 'wm_qos.correlation_id: 12345' 
--header 'wm_consumer.intimestamp: 1707204774000' 
--data '[{
    "name": " Beverages", 
    "status":"enabled", 
    "campaignId": 1234 
}]'

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
OkHttpClient client = new OkHttpClient().newBuilder().build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "
[
    {
        "name": "Beverages",
        "status": "enabled",
        "campaignId": 1234
    }
]");

Request request = new Request.Builder()
.url("https://developer.api.us.stg.walmart.com/api-proxy/service/sp/api-sams/v1/api/v1/adGroups")
.method("POST", body)
.addHeader("Authorization", "Bearer ***********")
.addHeader("Content-Type", "application/json")
.addHeader("wm_consumer.id", "**********************")
.addHeader("wm_sec.key_version", "2")
.addHeader("wm_sec.auth_signature", "************************")
.addHeader("wm_qos.correlation_id", "12345")
.addHeader("wm_consumer.intimestamp", "1707204774000")
.build(); 
 Response response = client.newCall(request).execute();  

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
const axios = require('axios'); 
let data = JSON.stringify([ 
{ 
    "name": "Beverages", 
    "status": "enabled", 
    "campaignId": 1234
} 
]); 
let config = { 
method: 'post', 
maxBodyLength: Infinity, 

url: 'https://developer.api.us.stg.walmart.com/api-proxy/service/sp/api-sams/v1/api/v1/adGroups', 

headers: {  
    'wm_consumer.id': '****************',  
    'wm_sec.key_version': '2',  
    'wm_sec.auth_signature': '**************',  
    'wm_qos.correlation_id': '12345',  
    'wm_consumer.intimestamp': '**************',  
    'Content-Type': 'application/json',  
    'Authorization': 'Bearer ****************' 
}, 
data : data 
}; 
axios.request(config) 
.then((response) => { 
console.log(JSON.stringify(response.data)); 
}) 
.catch((error) => { 
console.log(error); 
}); 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
import requests

url = "https://developer.api.us.stg.walmart.com/api-proxy/service/sp/api-sams/v1/api/v1/adGroups" 
payload = json.dumps([
{
    "name": "Beverages",
    "status": "enabled",
    "campaignId": 1234
}]) 
headers = {
'Authorization': 'Bearer ***************',
'Content-Type': 'application/json' 
'wm_consumer.id': '************',
'wm_sec.key_version': '2',
'wm_sec.auth_signature': '************',
'wm_qos.correlation_id': '12345',
'wm_consumer.intimestamp': '1707204774000',
}
response = requests.request("POST", url, headers=headers, data=payload)
print(response.text)

Response

Element Description Type
code Possible values of response code: success or failure String
details Details of the error if value of response code is failure String
adGroupId ID of the ad group Integer

Sample Response

[
    {
        "code": "success",
        "details": "", 
        "adGroupId": 600001
    }
]

HTTP Status Code

Status Code Description Possible Error Messages
400 Bad Request
  • Maximum allowed size in batch is 50
  • AdGroup name validation failed
  • Status validation failed
  • Campaign Id validation failed
  • empty input
  • Only 1 ad group is allowed in this campaign
  • You have exceeded the maximum number of 15000 adGroups per account. Please end existing campaigns to continue.
  • start time Date format incorrect
  • end time Date format incorrect
  • Total budget validation failed
  • Total budget should be more than 50
  • daily budget validation failed
  • daily budget should be more than 25
  • name should not be empty
  • Ad Group name should be unique within a Campaign
403 Forbidden
  • User not Authenticated
  • AdOps role does not access to any campaigns
  • You are not authorized to add adgroups to this campaign
404 Not Found Campaign not found
429 Too Many Requests <Exception Message>
500 Internal Server Error There was an error processing the request

List Ad Groups

Description: Retrieve all the ad group(s) for a specific campaign

End Point: /api/v1/adGroups

HTTP Method: GET

Query Parameters

Parameter Description Type Required Possible Values
advertiserId The ID of the advertiser for whom the ad group(s) should be returned Integer Y Unique numeric identifier
campaignId The ID of the campaign for which the ad group(s) should be returned Integer N Unique numeric identifier

Sample Request

1
2
3
4
5
6
7
8
9
curl --location  
'https://developer.api.us.stg.walmart.com/api-proxy/service/sp/api-sams/v1/api/v1/adGroups?advertiserId={advertiserId}&campaignId={campaignId}'
--header 'Authorization: Bearer ***********' 
--header 'Content-Type: application/json' 
--header 'wm_consumer.id: *************'
--header 'wm_sec.key_version: 2' 
--header 'wm_sec.auth_signature: *************' 
--header 'wm_qos.correlation_id: 12345' 
--header 'wm_consumer.intimestamp: 1707204774000' 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
OkHttpClient client = new OkHttpClient().newBuilder().build();
MediaType mediaType = MediaType.parse("text/plain");
RequestBody body = RequestBody.create(mediaType,"");
Request request = new Request.Builder()
.url("https://developer.api.us.stg.walmart.com/api-proxy/service/sp/api-sams/v1/api/v1/adGroups?advertiserId={advertiserId}&campaignId={campaignId}") 
.method("GET",body)
.addHeader("Authorization", "Bearer ***********")
.addHeader("Content-Type", "application/json")  
.addHeader("wm_consumer.id","**************")
.addHeader("wm_sec.key_version","2")
.addHeader("wm_sec.auth_signature","************")
.addHeader("wm_qos.correlation_id","12345")
.addHeader("wm_consumer.intimestamp", "1707204774000")
.build();
Response response = client.newCall(request).execute();  

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
const axios = require('axios'); 
let config = { 
method: 'get', 
maxBodyLength: Infinity, 

url: 'https://developer.api.us.stg.walmart.com/api-proxy/service/sp/api-sams/v1/api/v1/adGroups?advertiserId={advertiserId}&campaignId={campaignId}', 

headers: {  
    'wm_consumer.id': '****************',  
    'wm_sec.key_version': '2',  
    'wm_sec.auth_signature': '**************',  
    'wm_qos.correlation_id': '12345',  
    'wm_consumer.intimestamp': '**************' 
} 
}; 
axios.request(config) 
.then((response) => { 
console.log(JSON.stringify(response.data)); 
}) 
.catch((error) => { 
console.log(error); 
}); 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
import requests

url = "https://developer.api.us.stg.walmart.com/api-proxy/service/sp/api-sams/v1/api/v1/adGroups?advertiserId={advertiserId}&campaignId={campaignId}" 
payload = {}
headers = {
'Authorization': 'Bearer ***************' 
'Content-Type': 'application/json' ,
'wm_consumer.id': '************',
'wm_sec.key_version': '2',
'wm_sec.auth_signature': '************',
'wm_qos.correlation_id': '12345',
'wm_consumer.intimestamp': '1707204774000',
}
response = requests.request("GET", url, headers=headers, data=payload)
print(response.text)

Response

Element Description Type
adGroupId ID of the ad group Integer
name Name of the ad group String
status Status of ad group Status values: enabled, disabled, deleted String
campaignId ID of the campaign associated with the respective ad group Integer

Sample Response

[
    {
        "adGroupId": 500003,
        "name": "AdGroup 4",
        "status": "enabled", 
        "campaignId": 500002
    }
]

HTTP Status Code

Status Code Description Possible Error Messages
400 Bad Request advertiserId not found in request
403 Forbidden
  • User not Authenticated
  • AdOps role does not access to any campaigns
  • You don't have access to this advertiser
404 Not Found AdGroup not found
429 Too Many Requests <Exception Message>
500 Internal Server Error There was an error processing the request

Update Existing Ad Group

Description: To make changes in one or more existing ad groups. The existing AD group can be enabled, disabled or deleted.

End Point: /api/v1/adGroups

HTTP Method: PUT

Body Parameters

Parameter Description Type Required Possible Values
adGroupId The ID of the ad group. Required only if updating existing ad group Integer Y Unique numeric identifier
name The name of the ad group String N Relevant String value representing the ad group
status Status of ad group String N Status values can be: enabled, disabled, deleted

Sample Request

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
curl --location --request PUT 
'https://developer.api.us.stg.walmart.com/api-proxy/service/sp/api-sams/v1/api/v1/adGroups' 
--header 'Authorization: Bearer ***********' 
--header 'Content-Type: application/json' 
--header 'wm_consumer.id: *************' 
--header 'wm_sec.key_version: 2' 
--header 'wm_sec.auth_signature: *************' 
--header 'wm_qos.correlation_id: 12345' 
--header 'wm_consumer.intimestamp: 1707205605000' 
--data '[{
    "adGroupId": 1234,
    "name": "Soft Beverages",
    "status": "enabled"
}]'

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
OkHttpClient client = new OkHttpClient().newBuilder().build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType,
"[{
    "adGroupId": 1234,
    "name": "Soft Beverages",
    "status": "enabled"
}]");
Request request = new Request.Builder()
.url("https://developer.api.us.stg.walmart.com/api-proxy/service/sp/api-sams/v1/api/v1/adGroups") 
.method("PUT", body)
.addHeader("Authorization", "Bearer ***********")
.addHeader("Content-Type", "application/json")  
.addHeader("wm_consumer.id", "***********************")
.addHeader("wm_sec.key_version", "2")
.addHeader("wm_sec.auth_signature", "***********************")
.addHeader("wm_qos.correlation_id", "12345")
.addHeader("wm_consumer.intimestamp", "1707205605000")
.build(); 
Response response = client.newCall(request).execute();

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
const axios = require('axios'); 
let data = JSON.stringify([ 
{ 
    "adGroupId": 1234, 
    "name": "Soft Beverages", 
    "status": "enabled" 
} 
]); 
let config = { 
method: 'put', 
maxBodyLength: Infinity, 

url: 'https://developer.api.us.stg.walmart.com/api-proxy/service/sp/api-sams/v1/api/v1/adGroups', 

headers: {  
    'wm_consumer.id': '****************',  
    'wm_sec.key_version': '2',  
    'wm_sec.auth_signature': '**************',  
    'wm_qos.correlation_id': '12345',  
    'wm_consumer.intimestamp': '**************',  
    'Content-Type': 'application/json',  
    'Authorization': 'Bearer ****************' 
}, 
data : data 
    }; 
axios.request(config) 
.then((response) => { 
console.log(JSON.stringify(response.data)); 
}) 
.catch((error) => { 
console.log(error); 
}); 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
import requests
import json

url = "https://developer.api.us.stg.walmart.com/api-proxy/service/sp/api-sams/v1/api/v1/adGroups"
payload = json.dumps([
{
    "adGroupId": 1234,
    "name": "Soft Beverages",
    "status": "enabled"
}]) 
headers = {
    'Authorization': 'Bearer ***************' 
    'Content-Type': 'application/json' ,
    'wm_consumer.id': '************',
    'wm_sec.key_version': '2',
    'wm_sec.auth_signature': '************',
    'wm_qos.correlation_id': '12345',
    'wm_consumer.intimestamp': '1707205605000',
} 
response = requests.request("PUT", url, headers=headers, data=payload)
print(response.text)

Response

Element Description Type
code Status of the ad group update.Expected values: success or failure String
details Details of the update String
adGroupId ID of the ad group being updated Integer

Sample Response

[
    {
        "code": "success",
        "details": "", 
        "adGroupId": 500003
    },
    {
        "code": "failure",
        "details": " Ad Group Id validation failed", 
        "adGroupId": 0
    }
]

HTTP Status Code

Status Code Description Possible Error Messages
400 Bad Request
  • Maximum allowed size in batch is 50
  • AdGroup Id validation failed
  • AdGroup name validation failed
  • Status validation failed
  • Total budget validation failed
  • daily budget validation failed
  • Empty Input
  • start Date format incorrect
  • end Date format incorrect
403 Forbidden
  • User not Authenticated
  • AdOps role does not access to any campaigns
  • You don't have access to this advertiser
404 Not Found AdGroup not found
429 Too Many Requests <Exception Message>
500 Internal Server Error There was an error processing the request