Skip to content

Keywords

Overview

This API provides capability to fetch suggested keywords, listing all the keywords in a campaign, and adding and deleting keywords in a Keyword Bid campaigns.

Usage:

  • To get a list of suggested keywords based on the item added in the ad group
  • To list all the keywords that are part of a campaign
  • To Add more keywords to already existing keyword bid campaign with help of this method
  • To update current state and bid of existing keywords using this method

Limitations:

  • Maximum 50 keywords can be added for each request and total number of keywords can be added is 1000
  • For SBA campaign, only 200 distinct bid keywords with 1 to 3 keyword-match types for each are permitted to be enabled per ad group
  • Similar keyword with different match types will be counted as separate entries, example: laptop-exact match and laptop-broad match will count as two entries. All existing ad groups with more than 1000 keyword-match type combinations will continue to function normally but for SBA campaigns, a maximum of 1000 “keyword-match Type” combinations can be included.
  • All characters in a keyword must not be special characters (API allows special characters, needs ticket fix)
  • Limit on keyword character length is 80

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

Add Keywords

Description: Add keywords to already existing keyword bid campaign. You can add your own keywords as well.

End Point:  /api/v1/keywords

HTTP Method: POST

Body Parameters

Parameter
Description
 Type Required Possible Values
campaignId ID of the campaign Integer Y Unique numeric identifier
adGroupId ID of the group Integer Y Unique numeric identifier
matchType Matching criteria for the keywords String Y Values can be: exact, phrase, broad
bid Maximum cost per click for the keyword Double Y Valid bid value. Some facts about bid parameter: Minimum bid amount is:
  1. $0.20 for auto-bid campaigns
  2. $0.30 for keyword-bid campaigns
  3. $1.25 for Search Brand Amplifier campaigns

Bid amount will be restricted to first two decimal places for advertisers. Any decimal digit beyond the first 2 digits will be truncated without rounding off
state State of the keyword String Y Status values can be: Enabled, Paused, Archived
keywordText Text that defines the keyword String Y String value apt to the description of item

Sample Request

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
curl --location  
'https://developer.api.us.stg.walmart.com/api-proxy/service/sp/api-sams/v1/api/v1/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: 1707205605000'  
--data '[{
    "campaignId": 1234,
    "adGroupId": 1234,
    "matchType": "exact",
    "bid": 1.25,
    "state": "enabled",
    "keywordText": "battery"
}]'

 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
OkHttpClient client = new OkHttpClient().newBuilder().build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, 
"[
    {
        "campaignId": 1234,
        "adGroupId": 1234,
        "matchType": "exact",
        "bid": 1.25,
        "state": "enabled",
        "keywordText": "battery"
    }
]");
Request request = new Request.Builder()
.url("https://developer.api.us.stg.walmart.com/api-proxy/service/sp/api-sams/v1/api/v1/keywords") 
.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", "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
33
34
35
const axios = require('axios'); 
let data = JSON.stringify([  
{
    "campaignId": 1234,
    "adGroupId": 1234,
    "matchType": "exact",
    "bid": 1.25,
    "state": "enabled",
    "keywordText": "battery"
}
]); 
let config = { 
method: 'post', 
maxBodyLength: Infinity, 

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

headers: {  
    'wm_consumer.id': '****************',  
    'wm_sec.key_version': '2',  
    'wm_sec.auth_signature': '**************',  
    'wm_qos.correlation_id': '12345',  
    'wm_consumer.intimestamp': '**************',  
    'Content-Type': 'text/plain',  
    '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
22
23
24
import requests 

url = "https://developer.api.us.stg.walmart.com/api-proxy/service/sp/api-sams/v1/api/v1/keywords"
payload = "[
    {
        "campaignId": 1234,
        "adGroupId": 1234,
        "matchType": "exact",
        "bid": 1.25,
        "state": "enabled",
        "keywordText": "battery"
    }
 ]"
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("POST", url, headers=headers, data=payload) 
print(response.text)

Response

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

Sample Response

[
  {
    "code": "success",
    "details": " ",
    "keywordId": 600003,
    "keywordText": "text1"
  }
]

HTTP Status Code

Status Code Description Possible Error Messages
400 Bad Request
  • Only 1000 keyword allowed per request
  • Empty Input
  • adGroup not found
  • You are not allowed to add keywords for this campaign. Please check the campaign type.
  • You are not authorized to edit this adgroup
403 Forbidden
  • User not Authenticated
  • You do not have write permission to this advertiser
429 Too Many Requests <Exception Message>
500 Internal Server Error There was an error processing the request

List the Keywords

Description: List all the keywords that are part of a campaign.

End Point:  /api/v1/keywords

HTTP Method: GET

Query Parameters

Parameter Notes Type Required Possible Values
campaignId ID of the campaign Integer Y Unique numeric identifier

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/keywords?campaignId={campaignId}' 
--header 'Authorization: Bearer **************'  
--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' 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
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/keywords?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", "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
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/keywords?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
14
import requests 

url = "https://developer.api.us.stg.walmart.com/api-proxy/service/sp/api-sams/v1/api/v1/keywords?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': '1707205605000' 
} 
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 that is part of the campaign Integer
keywordId ID of the key word Integer
state State of the keyword. Values can be: Enabled, Paused, Archived String
keywordText Text that defines the keyword String
matchType Matching criteria for the keywords. Values can be: Exact, Pharse, Board String
bid Maximum cost per click for the keyword in dollars Double
status Status of the keyword added in the campaign and the values can be: approved, pending, rejected.
Note: By default it should be "pending" for each new or re-enabled keyword		 String

Sample Response

[
  {
    "campaignId": 1234,
    "adGroupId": 231,
    "keywordId": 567,
    "state": "enabled",
    "keywordText": "string",
    "matchType": "exact",
    "bid": 0.6,
    "status": "approved"
  }
]

HTTP Status Code

Status Code Description Possible Error Messages
400 Bad Request Campaign Id not found in the request
403 Forbidden User not Authenticated
404 Not Found Campaign not found
429 Too Many Requests <Exception Message>
500 Internal Server Error There was an error processing the request

Suggested Keywords

Description: Get a list of suggested keywords based on the item added in the ad group.

End Point:  /api/v1/keyword_suggestions

HTTP Method: ​GET

Query Parameters

Parameter Notes Type Required Possible Values
adGroupId ID of the group Integer Y Unique numeric identifier

Note: Suggested bid parameter is an automated bid-price recommendation based on winning bids for recent similar ads within the category. The suggested bid values are refreshed daily.

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/keyword_suggestions?adGroupId={adGroupId}'
--header 'Authorization: Bearer ***********'
--header 'accept: application/json'
--header 'WM_SEC.AUTH_SIGNATURE: ***********' 
--header 'WM_CONSUMER.ID: ***************' 
--header 'wm_qos.correlation_id: 12345'  
--header 'wm_consumer.intimestamp: 1707205605000' 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
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/keyword_suggestions?adGroupId={adGroupId}") 
.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", "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
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/keyword_suggestions?adGroupId={adGroupId}', 

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
14
import requests 

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

Response

Element Description Type
score Suggested keyword relevancy indicator. Score is simply a rank given to each keyword from 1 to n where n is the no. of keywords returned. Higher score represents higher relevancy. Double
query Suggested keyword for the item(s) added in the ad group String
suggestedBid Automated bid-price recommendations for exact match type Double
suggestedbidBroad Automated bid-price recommendations for board match type Double
suggestedbidExact Automated bid-price recommendations for exrta match type Double
suggestedbidPhrase Automated bid-price recommendations for pharse match type Double

Note: suggestedBid and suggestedbidExact are same in value

Sample Response

[
  {
    "score": 4,
    "query": "sample value key1 normalized",
    "suggestedBid": 1.42,
    "suggestedBidBroad": 1.42,
    "suggestedBidExact": 1.42,
    "suggestedBidPhrase": 1.42
  }
]

HTTP Status Code

Status Code Description Possible Error Messages
400 Bad Request
  • AdGroup Id not found in the request
  • Given ad group does not have any items. Please add items to get the keyword suggestions
403 Forbidden
  • User not Authenticated
  • 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 Keywords

Description: Update current state and bid of existing keywords.

End Point:  /api/v1/keywords

HTTP Method: PUT

Body Parameters

Parameter
Description
 Type Required Possible Values
keywordId ID of the keyword Integer Y Unique numeric identifier
bid Maximum cost per click for the keyword Double Y Valid bid value. Some facts about bid parameter: Minimum bid amount is:
  1. $0.30 for keyword bidding campaigns.
  2. $0.20 limit is for Auto bid campaigns.
  3. $1.25 for Search Brand Amplifier campaigns.

For a keyword bid, the maximum bid amount should not exceed $100. Bid amount will be restricted to first two decimal places for advertisers. Any decimal digit beyond the first 2 digits will be truncated without rounding off
state State of the keyword String Y Status values can be: Enabled, Paused, Archived

Note: Either one of “bid” or “state” parameters is mandatory

Sample Request

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
curl --location --request PUT 

'https://developer.api.us.stg.walmart.com/api-proxy/service/sp/api-sams/v1/api/v1/keywords' 
payload = "[ 
    {
        "keywordId": 1234,
        "bid": 2.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': '1707205605000'
} 
response = requests.request("PUT", url, headers=headers, data=payload) 
print(response.text) 

 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, 
"[
    {
        "keywordId": 1234,
        "bid": 2.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/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", "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([
{
    "keywordId": 1234,
    "bid": 2.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/keywords', 

headers: {  
    'wm_consumer.id': '****************',  
    'wm_sec.key_version': '2',  
    'wm_sec.auth_signature': '**************',  
    'wm_qos.correlation_id': '12345',  
    'wm_consumer.intimestamp': '**************',  
    'Content-Type': 'text/plain',  
    '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
22
import requests 

url = "https://developer.api.us.stg.walmart.com/api-proxy/service/sp/api-sams/v1/api/v1/keywords" 
payload = "[ 
      {
        "keywordId": 1234,
        "bid": 2.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': '1707205605000', 
} 
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 or failure String
details Details of the error if value of response code is failure String
keywordId ID of the keyword Integer

Sample Response

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

HTTP Status Code

Status Code Description Possible Error Messages
400 Bad Request
  • Keyword Id cannot be empty or zero in request
  • Keyword Bid cannot be negative
  • Nothing to update in request for some keywords. [Bid should be a non-negative number and allowed values for state are [enabled,paused, archived]].
  • duplicate keywordId present in the request
  • Campaign is Under review, changing keyword state is not allowed
  • as Keyword cannot be archived as the campaign has been live before
403 Forbidden User not Authenticated
404 Not Found keywordId is not found
429 Too Many Requests <Exception Message>
500 Internal Server Error
  • There was an error processing the request
  • Internal server error

Fetch keyword Analytics

Description: Perform keyword research and analysis for advertisers.

Note: Time period considered for results is last 30 days and 90 days from the same day last year to factor in seasonality.

End Point:  /api/v1/keywordAnalytics

HTTP Method: POST

Body Parameters

Parameter Description Type Required Possible Values
advertiserId ID of the advertiser Integer Y Unique numeric identifier
itemIds List of item ids that are part of campaign.
Note: Max limit on number of item ids is 10		 String array Y List of the Ids of items
adGroupId ID of the ad group that is part of the campaign Integer N 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/keywordAnalytics' 
--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 '[{
    "advertiserId": 1234,
    "adGroupId": 1234,
    "itemIds": ["prod11640583"]
}]

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
OkHttpClient client = new OkHttpClient().newBuilder().build();
MediaType mediaType = MediaType.parse("application/json");   
RequestBody body = RequestBody.create(mediaType, "{
    "advertiserId": 1234,
    "adGroupId": 1234,
    "itemIds": ["prod11640583"]
} ");
Request request = new Request.Builder()
.url("https://developer.api.us.stg.walmart.com/api-proxy/service/sp/api-sams/v1/api/v1/keywordAnalytics")
.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", "1707205605000") 
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([
{
    "advertiserId": 1234,
    "adGroupId": 1234,
    "itemIds": ["prod11640583"]
}
]); 
let config = { 
method: 'post', 
maxBodyLength: Infinity, 

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

headers: {  
    'wm_consumer.id': '****************',  
    'wm_sec.key_version': '2',  
    'wm_sec.auth_signature': '**************',  
    'wm_qos.correlation_id': '12345',  
    'wm_consumer.intimestamp': '**************',  
    'Content-Type': 'text/plain',  
    '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
import requests 

url = "https://developer.api.us.stg.walmart.com/api-proxy/service/sp/api-sams/v1/api/v1/keywordAnalytics"  
payload = "{
    "advertiserId": 1234,
    "adGroupId": 1234,
    "itemIds": [ "prod11640583"]
}"
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("POST", url, headers=headers, data=payload) 
print(response.text)

Response

Element Description Type
itemId Id of the item belonging to the campaign String
normalizedQuery A group of similar raw queries normalized into a single term by removing redundant information String
rawQuery Randomly chosen search keywords for a single item
Note: Maximum character length is 60 characters		 String
itemKeywordFrequency

A number of times, a keyword led to an item display. This element is based on the item’s appearance in the first 5 search result pages or in the top 200 results for the respective keywords. Possible values are: High, Medium, Low

 String
trafficKeywordFrequency Based on number of times when a keyword was searched.
Possible values are: High, Medium, Low		 String

Sample Response

[
  {
    "itemId": "45769024",
    "rawQuery": "key1",
    "normaliizedQuery": "key1 normalized",
    "itemKeywordFrequency": "Medium",
    "trafficKeywordFrequency": "High"
  }
]

HTTP Status Code

Status Code Description Possible Error Messages
400 Bad Request
  • You exceeded maximum item count of 10
  • AdvertiserId validation failed
  • You don't have access to this advertiser
  • Channel validation failed, valid values are 'WALMART' and 'ONLINE_GROCERY'
  • Item Id cannot be null
403 Forbidden User not Authenticated
429 Too Many Requests <Exception Message>
500 Internal Server Error There was an error processing the request

FAQs for Suggested Bids

Q: What are suggested bids? 
A: Suggested bids is a feature that provides strategic pricing guidance to advertisers who set up Manual and Automatic Sponsored Products campaigns on our platform. This feature provides advertisers with a starting point for bids and is designed to help increase the probability of winning auctions with competitive bid suggestions.

Example: If 5 items were served the last 30 days for laptop, the average winning bids for those items will be the suggested CPC bid for the keyword laptop.

Q: What new level recommendations are you offering your advertisers with the enhancements? 
A: We are providing product type level suggestions for Automatic campaigns and keyword level suggestions for Manual campaigns

Q: How often are suggested bids updated? 
A: They are updated daily for each campaign

Q: Will the suggested bids feature consider a campaign’s budget & duration? 
A: No. The objective of this feature is to increase the probability of winning the auction and does not contemplate campaign pacing 

Q: How do advertisers determine their starting bid? 
A: Our bid suggestion feature will help advertisers determine a starting bid for their SKUs and keywords   

Q: Will suggested bids be different at placement level? 
A: No, there will be one suggested bid for all placements. 

Q: Will each keyword match type have different bid suggestions? 
A: Yes, this feature offers different bid suggestions for the various match types, i.e., broad, phrase, and exact match keywords.

Q: When should advertiser use suggested bid? 
A:

  • When you need a comparison point: If you already know what your average CPC (Cost per Click), then the Suggested Bid can provide a helpful comparison point.
  • Looking for competitive insights: The suggested bid can give advertisers helpful insight into what the competition is bidding on and provide a good place to start.

Q: What is changing with the launch of suggested bid enhancements?
A: See the pre and post launch comparison matrix below:

Pre vs Post Comparison Suggested Bids (Legacy/Pre-Enhancement) Suggested Bids (With Enhancement)
Suggestion level 1. Category (auto campaigns)
2. Category (manual campaigns)		 1. Product type (auto campaigns)
2. Keyword – match type (manual campaigns)
Supported KW match type (Manual campaigns) None/Exact match All match types (exact, phrase, broad)
Placement Level All placements All placements

Q: Are there any changes to the current suggest bids API endpoint?
A: While there are no changes to the suggested bids API endpoint, there are additional fields that will be available in the JSON response.

Q: Are suggested bids & exact match suggested bids the same? 
A: Yes, the current suggested bids and exact match suggested bids are the same.