These APIs provide capabilities to fetch suggested keywords, listing all the keywords in a campaign, and adding and deleting keywords in a Keyword Bidded campaigns.
Notes:
A maximum of 220 suggested keywords can be fetched at once
A maximum of 50 keywords can be created/updated in a single POST/PUT batch request
For a Sponsored Brands (earlier known as Search Brand Amplifier or SBA) campaign and a Sponsored Videos campaign , only 200 distinct bidded keywords with 1 to 3 keyword-match types for each are permitted to be enabled per ad group
For non-Sponsored Brands campaigns, a maximum of 1000 “keyword-matchType” combinations can be included in an ad group Note:
Similar keyword with different match types will be counted as separate entries e.g.: 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
All characters in a keyword must not be special characters
Limit on keyword character length is 80
Suggested Keywords
Description
Get a list of suggested keywords based on the item added in the ad group.
URL: GET/api/v1/keyword_suggestions
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.
Query Parameters
Parameter
Notes
Type
Required
Possible Values
adGroupId
ID of the ad group
integer
Y
Unique numeric identifier
Headers
Header Name
Description
Required
Values
Authorization
The token will provide you the access to the API. It is same for all advertisers you access through the API
Y
Please utilize the generated auth_token shared with you at the time of partner onboarding from the Getting Started Guide
WM_SEC.KEY_VERSION
We will provide you with the KEY VERSION to access the API. It is same for all advertisers you access through the API
Y
1
WM_CONSUMER.ID
We will provide you the consumer ID to access the API. It is same for all advertisers you access through the API.
Y
Please 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_SIGNATURE
Auth signature as an API key
Y
Use the signature generator code from Getting Started Guide to generate this value
WM_CONSUMER.intimestamp
Timestamp for which the auth signature is generated. Use Unix epoch format for the timestamp
Y
Use the signature generator code (Getting Started Guide) to generate this value
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 broad match type
double
suggestedbidExact
Automated bid-price recommendations for exact match type
double
suggestedbidPhrase
Automated bid-price recommendations for phrase match type
double
Note:suggestedBidand suggestedbidExactare same in value.
ID of the ad group that is part of the above 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, phrase, broad
string
bid
Maximum cost per click for the keyword in dollars
double
status
Status of the keyword added in the campaign. Values can be: approved, pending, rejected \Note: The “status” for each new or re-enabled keyword be set to “pending” by default
Add more keywords to already existing keyword bidded campaign with help of this method. You can add your own keywords as well.
URL: POST/api/v1/keywords
Query Parameters
Parameter
Notes
Type
Required
Possible Values
campaignId
ID of the campaign
integer
Y
Unique numeric identifier
adGroupId
ID of the ad group that is part of the above campaign
integer
Y
Unique numeric identifier
state
State of the keyword
string
Y
State values can be: enabled, paused, archived
keywordText
Text that defines the keyword
string
Y
String value apt to the description of item
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: a) $0.30 for keyword bidding campaigns b) $0.20 limit is for Auto bid campaigns c) $1 for Sponsored Brands campaigns d) $1.30 for Sponsored Videos campaigns
For a keyword bid, 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
You can update current state and bid of existing keywords using this method.
URL: PUT/api/v1/keywords
Query Parameters
Parameter
Notes
Type
Required
Possible Values
keywordId
ID of the keyword
integer
Y
Unique numeric identifier
state
State of the keyword
string
N
State values can be: enabled, paused, archived
bid
Maximum cost per click for the keyword
double
N
Valid bid value. Minimum bid amount is: a) $0.30 for keyword bidding campaigns b) $0.20 limit is for Auto bid campaigns c) $1 for Sponsored Brands campaigns d) $1.30 for Sponsored Videos 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.
For a keyword bid, maximum bid amount should be less than or equal to $100.
Note: You must provide at least one of “bid” or “state” parameters.
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 cost-per-click
bid for the keyword laptop.
Q: What new level recommendations are you offering your
advertisers with the enhancements?
We are providing product type level suggestions for Automatic
campaigns and keyword level suggestions for Manual campaigns.
Q: How often are suggested bids updated?
They are updated daily for each campaign.
Q: Will the suggested bids feature consider a
campaign’s budget & duration?
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?
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?
No, there will be one suggested bid for all placements.
Q: Will each keyword match type have different bid
suggestions?
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?
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?
See the pre and post launch comparison matrix below:
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?
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?
Yes, the current suggested bids and exact match
suggested bids are the same.
Rate limits on API operations
There is a rate
limit in place on the allowed number of API operations per hour.
Operations per hour are computed as the sum of number of changes requested across all API requests during the hour.
For example, 5 keyword bid changes, creation of an ad group, adding an item, and a snapshot report request in any given hour, would be counted as 8 operations.
You will
receive an HTTP 429 status error code and an error message about rule enforced
in case of breaking ops limit.
To learn more
about current applicable limits specific to your integration, please reach out
to the API Partner Enablement team.