Skip to content

Negative Keywords

Overview

Manage negative keywords that operate on pages that display grid search results for manual and automatic campaigns. Negative keywords consist of a single word or phrase that prevents your ad from being promoted in grid display when the user search has an exact match with a keyword entry. Negative keywords only function when there is an EXACT MATCH with a search term.

Examples of exact match:

  • If an ad group has the word "Pepsi" as a negative keyword and a user searches for "cherry Pepsi," the Sam's Club website can display "Pepsi" items as sponsored products because cherry Pepsi is not an exact match with the negative keyword
  • If you configured the ad group such that the term "Pepsi cola" is a negative keyword, the ad group is not blocked when the user search simply includes "Pepsi"

Note: Negative keywords do not affect the content of search-brand amplifier ads

Use Case: As an advertiser, you can use a manual or automatic campaign to promote a product. You don't need to spend for brand name keyword matches because the product already gets displayed based on other criteria.  Negative keywords provide the capability to exclude the brand from being promoted with in-grid display. Designating a brand name as a keyword is the most common use case for this API.

Limitations:

  • Maximum 50 negative keywords can be added for each request and total number of negative keywords can be added is 1000
  • Limit on keyword character length is 80

To understand details about ‘Request Header' and 'Authorization’ are available in the .

List All Negative Keywords

Description: Retrieve the list of all the negative keywords in the campaign.

End Point:  /api/v1/negative_keywords

HTTP Method: GET

Query Parameters

Parameter Description Type Required Possible Values
advertiserId ID of the advertiser Integer Y Unique numeric identifier
campaignId ID of the campaign Integer Y Unique numeric identifier

NOTE: The following headers apply to all the Negative Keyword API calls.

Sample Request

1
2
3
4
5
6
7
8
curl --location 
'https://developer.api.us.stg.walmart.com/api-proxy/service/sp/api-sams/v1/api/v1/negative_keywords?campaignId={campaignId}&advertiserId={advertiserId}'
--header 'Authorization: Bearer ***************' 
--header 'accept: application/json' 
--header 'WM_SEC.AUTH_SIGNATURE: ***********' 
--header 'WM_SEC.KEY_VERSION: *' 
--header 'WM_CONSUMER.ID: ***************' 
--header 'WM_CONSUMER.intimestamp: 1565309779' 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
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/negative_keywords?advertiserId={advertiserId}&campaignId={campaignId}")
.method("GET", body)
.addHeader("Authorization", "Bearer ***************")
.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", "1700221256000").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
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/negative_keywords?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': '**************',  
    'Authorization': 'Bearer ****************' 
} 
}; 
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
import requests
url = "https://developer.api.us.stg.walmart.com/api-proxy/service/sp/api-sams/v1/api/v1/negative_keywords?advertiserId={advertiserId}&campaignId={campaignId}"
payload = {}
headers = {
    'Authorization': 'Bearer ***************',
    'wm_consumer.id': '**************',
    'wm_sec.key_version': '2',
    'wm_sec.auth_signature': '**********',
    'wm_qos.correlation_id': '12345',
    'wm_consumer.intimestamp': '1707201981000'
}
response = requests.request("GET", url, headers=headers, data=payload)
print(response.text)

Response

Element Description Type
campaignId ID of the campaign Integer
adGroupId ID of the ad group Integer
keywordId ID of the keyword Integer
state State of the keyword String
keywordText Text that defines the keyword String
negativeMatchType Matching criterion for the negative keywords. negativeExact is the only match type for negative keywords. String

Sample Response

[
    {
        "campaignId": 15812,
        "adGroupId": 770833893,
        "keywordId": 12347,
        "state": "enabled",
        "keywordText": "Pepsi",
        "negativeMatchType": "negativeExact"
    },
    {
        "campaignId": 15812,
        "adGroupId": 770833893,
        "keywordId": 12348,
        "state": "enabled",
        "keywordText": "Kellogg's",
        "negativeMatchType": "negativeExact"
    }
]

Add Negative Keywords

Description: Add negative keywords to an existing campaign.

End Point:  /api/v1/negative_keywords

HTTP Method: POST

Query Parameters

Parameter Description Type Required Possible Values
campaignId ID of the campaign Integer N Unique numeric identifier

Body Parameters

Parameter Description Type Required Possible Values
campaignId ID of the campaign Integer Y Unique numeric identifier
adGroupId ID of the ad group Integer Y Unique numeric identifier
negativeMatchType Matching criterion for negative keywords String Y Only negativeExact is supported for all campaign types (Auto, Manual, and SBA)
state Indicates if negative keyword matching is enabled String Y enabled disabled
keywordText Ad keyword(s) that when matched to search term excludes the ad from sponsored display String Y Any descriptor applied to the product

Sample Request

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
curl --location POST 
'https://developer.api.us.stg.walmart.com/api-proxy/service/sp/api-sams/v1/api/v1/negative_keywords'
--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_consumer.intimestamp: 1700221256000' 
--data '[{
    "campaignId": 1234,
    "adGroupId": 1234,
    "negativeMatchType": "negativeExact",
    "state": "enabled",
    "keywordText": "SampleNegative"
}]'

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
OkHttpClient client = new OkHttpClient().newBuilder().build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, 
"[
    {
        "campaignId": 1234,
        "adGroupId": 1234,
        "negativeMatchType": "negativeExact",
        "state": "enabled",
        "keywordText": "SampleNegative"
    }
]");
Request request = new Request.Builder()
.url("https://developer.api.us.stg.walmart.com/api-proxy/service/sp/api-sams/v1/api/v1/negative_keywords")
.method("POST", body)
.addHeader("Authorization", "Bearer ***********************")
.addHeader("wm_consumer.id", "***************")
.addHeader("wm_sec.key_version", "2")
.addHeader("wm_sec.auth_signature", "***************")
.addHeader("wm_consumer.intimestamp", "1700221256000")
.addHeader("Content-Type", "application/json").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
33
const axios = require('axios'); 
let data = JSON.stringify([ 
{ 
    "campaignId": 1234, 
    "adGroupId": 1234, 
    "negativeMatchType": "negativeExact", 
    "state": "enabled", 
    "keywordText": "SampleNegative" 
} 
]); 
let config = { 
method: 'post', 
maxBodyLength: Infinity, 

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

headers: {  
    'wm_consumer.id': '****************',  
    'wm_sec.key_version': '2',  
    'wm_sec.auth_signature': '**************',  
    '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/negative_keywords"
payload = json.dumps([
{
    "campaignId": 1234,
    "adGroupId": 1234,
    "negativeMatchType": "negativeExact",
    "state": "enabled",
    "keywordText": "SampleNegative"
}])
headers = {
    'Authorization': 'Bearer ***********************',
    'Content-Type': 'application/json',
    'wm_consumer.id': '***************',
    'wm_sec.key_version': '2',
    'wm_sec.auth_signature': '***************',
    'wm_consumer.intimestamp': '1700221256000'
}
response = requests.request("POST", url, headers=headers, data=payload)
print(response.text)

Response

Element Description Type
code The response code can have following values: success, failure String
details Details of the error if value of response code is failure String
keywordId Five-digit ID of the keyword Integer
keywordText Text that defines the keyword String

Sample Response

[
  {
    "code": "success",
    "details": " ",
    "keywordId": 12349,
    "keywordText": "Pepsi"
  }
]

Update Negative Keyword

Description: Update the state of existing keywords.

End Point: /api/v1/negative_keywords

HTTP Method: PUT

Query Parameters

Parameter Description Type Required Possible Values
advertiserId ID of the ad advertiser Integer N Unique numeric identifier
campaignId ID of the ad campaign Integer N Unique numeric identifier

Body Parameters

Parameter Description Type Required Possible Values
keywordId Five-digit ID of the campaign Integer Y Unique numeric identifier
state ID of the ad group String Y Unique numeric identifier

Sample Request

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
curl --location PUT 
'https://developer.api.us.stg.walmart.com/api-proxy/service/sp/api-sams/v1/api/v1/negative_keywords' 
--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: 1700221256000' 
--data '[{
    "keywordId": 0,
    "state": "enabled"
}]'

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
OkHttpClient client = new OkHttpClient().newBuilder().build();
MediaType mediaType = MediaType.parse("text/plain");
RequestBody body = RequestBody.create(mediaType, 
"[
    {
        "keywordId": 0,
        "state": "enabled"
    }
]");
Request request = new Request.Builder()
.url("https://developer.api.us.stg.walmart.com/api-proxy/service/sp/api-sams/v1/api/v1/negative_keywords")
.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", "1700221256000")
.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
const axios = require('axios'); 
let data = JSON.stringify([ 
{ 
    "keywordId": 0, 
    "state": "enabled" 
} 
]); 
let config = { 
method: 'put', 
maxBodyLength: Infinity, 

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

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
import requests
url = "https://developer.api.us.stg.walmart.com/api-proxy/service/sp/api-sams/v1/api/v1/negative_keywords"
payload = "[{
    "keywordId": 0,
    "state": "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": "1700221256000"
}
response = requests.request("PUT", url, headers=headers, data=payload)
print(response.text)

Response

Element Description Type
code The response code can have following values: success, failure String
details Details of the error if value of response code is failure String
keywordId Five-digit ID of the keyword Integer

Sample Response

[
    {
        "code": "success",
        "details": "",
        "keywordId": 12349
    }
]