Ad Items

Ad Item endpoint limitations:

1. A maximum of 50 ad items can be added to an ad group in a single POST batch request
2. A maximum of 50 ad items can be updated in a single PUT batch request
3. A maximum of 2000 ad items can be added to an ad group for Auto Bid and Keyword Bidded campaigns
4. For Sponsored Brands (earlier known as Search Brand Amplifier or SBA) campaigns, you need to add minimum 2 ad items to an ad group. it is required to have at minimum 2 ad items in an ad group
5. For Sponsored Videos campaigns , you need to add minimum 1 ad item to an ad group.
6. A maximum of 10 ad items are allowed to be added to an ad group for Sponsored Brands and Sponsored Videos campaigns

Note:

1. We recommend adding at least 3 ad items to an ad group for Sponsored Brands campaigns and Sponsored Videos campaigns . This helps avoid ads from not serving due to an out-of-stock scenario
2. If only 1 ad item remains eligible to serve in a campaign, the ad will stop serving on Desktop but continue to serve on Mobile for Sponsored Brands

Possible Reasons of Item Upload Failure:

Please note following scenarios to avoid an item upload failure:

1. When an item is not owned by the advertiser
2. When item id is incorrect or not found in catalog
3. You cannot upload variant items for campaign types Sponsored Brands and Sponsored Videos . We currently support advertising variant items for campaign type Sponsored Products only
4. You cannot upload an unpublished item. However, if a published item, added to the campaign  becomes unpublished, you can still update it. Please note that ad will stop serving for the item that becomes unpublished after it was added
5. You cannot promote a virtual pack/bundle (multiple of a primary variant item (ex. 2-pack) grouped as one  item) without the assistance of a Walmart support agent at this time. In this case, please submit a support ticket (via https://advertisinghelp.walmart.com/s/contact) with the API Partner Enablement team for assistance in promoting this item.

Description

With help of GET operation, retrieve the list of all the products added to the campaign catalog.

URL: GET/api/v1/adItems

Query Parameters

Parameter	Notes	Type	Required	Possible Values
auth_token	The token will provide you the access to the API. It is same for all advertisers you access through the API.	string	Y	Please utilize the generated auth_token shared with you at the time of partner onboarding from the Getting Started Guide
campaignId	Id of the campaign where the ad group belongs	integer	Y	Unique numeric identifier

Headers

Header Name	Description	Required	Values
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

Sample Request

curl -X GET "https://developer.api.stg.walmart.com/api-
proxy/service/WPA/Api/v1/api/v1/adItems?campaignId=5601&auth_token=1234"
-H "WM_SEC.AUTH_SIGNATURE: ***********" 
-H "WM_CONSUMER.ID: adfwe-v23-faasd2r-afs-asdfqeff" 
-H "WM_CONSUMER.intimestamp: 1565309779"
-H "accept: application/json"

Response

Element	Description	Type
campaignId	ID of the campaign	integer
adGroupId	ID of the ad group that is part of the campaign	integer
itemId	ID of the products that are being listed by this GET operation	string
adItemId	A product can be part of several Ad groups. adItemId is ID of the product that ties it to a specific ad group.	integer
bid	Cost per click set for the item	double
status	Specified status of ad item Status values: enabled, disabled	string
itemImageUrl	URL for image of Item	string
itemPageUrl	URL for item page	string
name	Name of the ad item	string
reviewStatus	Review outcome for the item. The values are: pending, approved, rejected	string
reviewReason	Description of why an item was rejected in review of Sponsored Brands ad group. more details can be found in overall review comments for the ad group if marked as “Other”.	string

Sample Response

[
  {
    "campaignId": 600001,
    "adGroupId": 600003,
    "itemId": 45769024,
    "adItemId": 600004,
    "bid": 0.6,
    "status": "enabled",
    "itemImageUrl": "https://i5.walmartimages.com/asr/905eb620-b036-48e9-b8df-8a00257efca0_1.cd6ce64707093979d61b67379b985e1d.jpeg?odnHeight=450&odnWidth=450&odnBg=ffffff",
    "itemPageUrl": "https://www.walmart.com/ip/45769024",
    "name": "TV Console",
    "reviewStatus": "pending ",
    "reviewReason ": "text123"
  }
]

Description

With the help of POST operation, add new ad item to the ad group in a campaign.

URL: POST/api/v1/adItems

Query Parameters

Parameter	Notes	Type	Required	Possible Values
campaignId	ID of the campaign where the ad group belongs	integer	Y	Unique numeric identifier
adGroupId	ID of the ad group that is part of the campaign	integer	Y	Unique numeric identifier
itemId	ID of the product that is being added to ad group	string	Y	String identifier
bid	Maximum cost per click for the item in an auto bidding campaign. Note: Bids on keywords in keyword-bid campaign supersede the item bid you set for items in keyword-bid campaign	double	Y	Bid values can be: 1. In dollars 2. Minimum bid amount is a. $0.20 for auto-bid campaigns b. $0.30 for  keyword-bid campaigns c. $1 for Sponsored Brands campaigns d. $1.30 for Sponsored Videos campaigns 3. 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.
status	Specified status of ad item	string	Y	Status values can be: enabled, disabled, deleted Note: You cannot delete an item from a campaign that has gone live

curl -X POST 
"https://developer.api.stg.walmart.com/api-proxy/service/WPA/Api/v1/api/v1/adItems?auth_token=1234"
-H "accept: application/json",
-H "WM_SEC.AUTH_SIGNATURE: ***********" 
-H "WM_CONSUMER.ID: adfwe-v23-faasd2r-afs-asdfqeff" 
-H "WM_CONSUMER.intimestamp: 1565309779",
-H "Content-Type: application/json" 
-d " 
{ "campaignId": 600001,
"adGroupId": 600003,
"itemId": "45673892",
"bid": .6,
"status": "enabled"
}

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
adItemId	ID of the ad item	integer

Sample Response

[
  {
    "code": "success",
    "details": "",
    "adItemId": 600001
  },
  {
    "code": "failure",
    "details": "error message",
    "adItemId": 0
  }
]

Description

Update an existing ad item in an ad group using PUT operation.

URL: PUT/api/v1/adItems

Query Parameters

Parameter	Notes	Type	Required	Possible Values
campaignId	ID of the campaign where the ad group belongs	integer	Y	Unique numeric identifier
adGroupId	ID of the ad group that is part of the campaign	integer	Y	Unique numeric identifier
itemId	ID of the product that is being added to ad group	string	Y	String identifier
bid	Maximum cost per click for the item in an auto bidding campaign. Note: Bids on keywords in keyword-bid campaign supersede the item bid you set for items in keyword-bid campaign	double	Y	Bid values can be: 1. In dollars 2. Minimum bid amount is: a. $0.20 for auto-bid campaigns b. $0.30 for  keyword-bid campaigns c. $1 for Sponsored Brands campaigns d. $1.30 for Sponsored Videos campaigns 3. 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.
status	Specified status of ad item	string	Y	Status values can be: enabled, disabled, deleted Note: You cannot delete an item from a campaign that has gone live

Sample Request

curl -X PUT "https://developer.api.stg.walmart.com/api- proxy/service/WPA/Api/v1/api/v1/adItems?auth_token=1234" 
-H "accept: application/json" 
-H "WM_SEC.AUTH_SIGNATURE: ***************" 
-H "WM_CONSUMER.ID: adfwe-v23-faasd2r-afs-asdfqeff"
-H "WM_CONSUMER.intimestamp: 1565309779" 
-H "Content-Type: application/json" 
-d " 
{"campaignId": 600001,
" adGroupId": 600003,
"itemId": "45673892",
"bid": .6,
"status": "enabled"}
"

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
adItemId	ID of the ad item	integer

Sample Response

[
  {
    "code": "success",
    "adItemId": "600002",
    "details": ""
  },
  {
    "code": "failure",
    "adItemId": "0",
    "details": "Bid should be higher than: 5.0"
  }
]

General FAQs:

What is a primary variant within Sponsored Product campaigns?

A. A primary variant is the item to which all the other items within the variant group are mapped to. A primary variant was previously known as the “base item”. It is important to note that with the launch of variant bidding all variants, including the primary variant, can be promoted, and displayed within sponsored product campaigns.

Q. What is a variant item?

A. Every item within your variant group is now a variant item, any eligible item is now able to be promoted within sponsored product campaigns.

Q. What is the current experience vs the future experience when variant bidding launches? What is changing with variant bidding?

1. Before variant bidding:  Advertisers can only promote primary variant (formerly known as base item) within sponsored product campaigns
2. With variant bidding: The launch of Variant Bidding will enable advertisers to bid on all their items, including both the primary variant and all variant items. All items will now be variants and you can choose the one you would like to advertise by adding the respective item ID to your Sponsored Products campaign

Example: if the black shirt is the primary variant today and appearing within sponsored search results, but the variants are red, green, blue, these are now eligible to be promoted and appear in Sponsored Products campaigns, so factors that make variants could be color, size, count, etc.

Q. Is Variant bidding only available for sponsored product campaigns?

A. Yes, variant bidding is for Sponsored Products only. Both automatic and manual campaigns. Variant bidding is NOT available for SBA (sponsored brands).

Q: Are all items’ variants within my portfolio?

A: Yes, any items in your portfolio can now be promoted so you can choose any variant to be displayed within sponsored search (Sponsored Products only).

Q: What benefits does promotion of variant items provide for the customer?

A: Optimal customer experience by providing options that are variants which correlate to search results. It is designed to increase the discovery of additional or popular items for the customer.

Q. Which ad placements can variant items be advertised in? (Does not apply to the primary variant)

A.  Variant bidding will be available for the following:

1. Search in-grid
2. SP product carousels
3. Buy Box
4. Stock up

Variant bidding will NOT be available for:

1. Browse in-grid
   
   

Q. Can the primary variant be advertised in all placements for Sponsored Products?

A. Yes

Q. Will the variants in the same product variant group compete for winning ad slots? If yes, please share more details.

A. Just like how it works today, if you are advertising similar items or the same item in multiple campaigns/ad groups they will compete against one another. The winning ad will be based on relevancy and bid

• Search In-grid
  a. Only one item per variant group will be displayed for categories
  where many variants exist, and many brands/sellers are promoting
  multiple variants (i.e., Apparel
  b. Multiple items per variant group potentially can be displayed for
  certain categories (i.e., consumables)
  These are everyday items where we enable faster basket building

1. Carousels
   a. Multiple items per variant group potentially can be displayed at the
   same time

Q. If a primary variant has been historically advertised, will that have a higher chance showing up over other variants that are not primary?

A. Not necessarily. Historical performance plays a factor in an item showing up in sponsored product campaigns, as well as many other factors such as relevancy to search query, customer intent, ad item contextual relevance, and max bid price.

Q. Is variant bidding a cold start solution?

A. No, variant bidding is not a cold start solution.  Variant bidding gives advertisers the flexibility to advertise any item within your portfolio which may lead to increased visibility. Advertising variant items will use the same factors as current item relevance does (customer intent, ad item contextual relevance, historical performance).

Q. How do I know which variant item to advertise?

A. You can advertise any variant item within your portfolio.  Determine which items are the most important to what goals you are trying to achieve on walmart.com. It can be you want to promote your most popular items, your most profitable items, seasonal items, items that you think will have the most volume of sales.  Refer to our best practices guides for some more tips.

Q. If I am advertising all the variants with the same set of keywords, will WMT choose the variant product based on the keyword relevancy, inventory availability and Buy Box win for ads promotion?

A. Yes, ad serving will continue to work the same way it works today in our Advanced Second Price Auction. Item needs to be published, in stock, winning the buy box. Once the algorithm establishes the relevant products competing for placements, it looks at each product’s relevance (historical performance, customer intent, ad item contextual relevance) and max bid price and determines the auction winners

Q: Can I promote any item in my portfolio?

A: Yes, you may promote any item that is eligible within your portfolio.

Q. I’m promoting X # of variants but only one variant keeps winning (get the most impression) most of the time. How should I proceed?

A. Look at our Sponsored Product tools such as the item health report, or the keyword performance. Think about the keywords you are bidding on for each variant item. Think about the bid price you are promoting for each variant. Look at the popularity for each variant. Create new campaigns and use unique identifiers for your keyword list.  Refer to our best practices guide for more information. Lastly ensure your PDP pages are fully up to date and filled out correctly.

Q. Will suggested bids still be provided for variant items?

A. The bid suggestions will be at a product level when variant bidding launches for automatic campaigns.

Q: How many items can I add to the ad group within a sponsored product campaign?

A. The current limit per ad group, as it exists today, is 2,000 items and will remain the same for variant bidding. The user is shown a warning label that they have reached the limit.

Q. Can variants be added to existing campaigns? (in-flight campaigns)?

A. Yes, variants can be added to existing campaigns.

Q: Will historical performance play a factor when I promote my variant item?

A: Historical performance will play a factor to a certain extent. Variant items will follow the current 2PA auction methodology, ad relevance will continue to play a key role in determining winning ads.  While the bid price will allow all relevant qualifying ads to compete for better in-grid placements.

Q. If I click on the variant displayed in Sponsored Search, but I click into the page and purchase a different variation, how will my sales be reported? (Will I be able to see where the sale came from vs where it advertised?)

A. As it works today whichever variant item is clicked on in the sponsored search will get the attribution. 

Q. Will item health report now include variants?

A. Yes, the item health reports will include all variant items, it will also show the respective variant item id, and show which primary variant it is mapped to.

Q: What reports can I use to optimize my variant bidding strategy

A.

1. Item recommendations
   Keyword recommendations
2. Item Health report
3. Item Keyword Performance Report 
4. Item Performance
5. Keyword Performance
6. Top Search Trends- WPP only

Click here For more information on Variant group FAQs

Variant bidding lets Walmart Sponsored Products advertisers promote any variation of an item in their catalog — including sizes, colors, counts and patterns. This strategy is designed to help improve item discoverability and conversion: Giving Walmart customers multiple buying options in one place makes it easier for them to find exactly what they’re looking for without having to browse hundreds of items across search results.

Start with these high-level best practices, then test and learn to refine your strategy to fit your category, brand, and business goals:

Structuring your Sponsored Products campaign 

There are always questions about the right way to structure campaigns, especially Manual campaigns — and variants in the mix can make that question more complicated. No one structure is better than the others, but we suggest:

1. Keywords

a. Campaigns with general keywords
b. Include all variants that share similar attributes
c. Campaigns with variant-specific keywords
d. Create ad groups of variants that fit specific keywords

2. Keywords tip

Test and learn different keyword combinations to determine whether to assign general or variant-specific keywords to the variants you wish to promote. For example, if you sell a shirt that comes in black, white, and green:

a. The search term “men’s shirt” can apply to any of these color variants
b. The search term “men’s green shirt” can only apply to the green variant

If you notice that “men’s shirt” delivers sales of green shirts—because the green shirt is a popular item—you could continue both keyword strategies. Figuring out what the customer is looking for will help you determine which keywords to map to which variant items.

3. Choosing items to promote

Focus on the top variants, bestsellers, top-priority items, and seasonal items. that are generating the most conversions and sales.
Items tip: Don’t just throw it all into a campaign from your variant group. Keep the 80:20 rule in mind.

4. Relevancy

a. Your items’ relevancy to the customer’s search query is the key factor that
determines the position of your ads and the cost-per-click price you’ll pay.
Review or  search relevancy best practices for more information
b. Update and/or expand item page content as necessary for each variant
you choose to promote. For more information, review our content quality
guide and listing quality guides for Walmart suppliers or Walmart
Marketplace sellers. 

5. Choosing variants to promote

a. Start by promoting your top-converting, bestselling, or seasonal variants
b. Focus on the top variants that are generating the most conversions and
sales
Promote these top-high converting variants for generic keywords (w/
broad match)
c. Other variants for intent keywords (w/ exact match or phrase match)

Example: Men’s T-shirt with six color variants

d. You want to promote the top-converting variants to align with your
business goals
e. Your catalog dashboard indicates that the black and white variants
convert the most often
f. Create a new Sponsored Products campaign for the black and white
variants
g. Choose the variant-specific search terms “white T-shirt” and “black T-
shirt” 
h. Use all three match types (broad, phrase and exact) for these search
terms
i. Continue to promote other variants using a slightly different bidding
strategy
Create campaigns with unique identifiers, such as sizes, for your
keyword list. (This helps avoid cannibalization, and longer-tail
keywords tend to have a lower cost-per-click.)

6. Optimization tools & Reports that help inform variant bidding strategy

a. Item recommendations
Keyword recommendations
b. Item Health report
c. Item Keyword Performance Report
d. Item Performance
e. Keyword Performance
f. Top Search Trends- WPP only

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.