Skip to content

Ad Items

Overview

Ad Items API is used to fetch, update all the advertising items added to the campaign catalog.

Usage:

  • To retrieve and update the list of all the advertising items added to the campaign catalog
  • Helps in streamlining the campaign creation process and makes it easier to optimize campaigns

Limitations:

  • A maximum of 50 ad items can be added to an ad group in a single POST batch request
  • A maximum of 50 ad items can be updated in a single PUT batch request
  • A maximum of 2000 ad items can be added to an ad group for "Auto Bid" and "Keyword Bid" campaigns
  • For Search Brand Amplifier or SBA campaigns, you need to add minimum 3 ad items to an ad group. This helps avoid ads from not serving due to an out-of-stock scenario.
  • A maximum of 10 ad items are allowed to be added to an ad group for Search Brand Amplifier campaigns

Note:

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 Search Brand Amplifier (SBA).

Possible Reasons of Item Upload Failure:

Please consider following scenarios to avoid an item upload failure

  • When an item is not owned by the advertiser
  • When item ID is incorrect or not found in catalog
  • 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

Details about ‘Request Header' and 'Authorization’ are available in the Authorization Guide

List Ad Items in a Campaign

Description: Used to retrieve the list of all the products added to the campaign catalog.

End Point: /api/v1/adItems

HTTP Method: GET

Query Parameters

Parameter Description Type Required Possible Values
campaignId ID of the campaign where the ad group belongs 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/adItems?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/adItems?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
22
23
24
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?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/adItems?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
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 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. Expected values: pending, approved, rejected. String
reviewReason Reason for rejection of Search Brand Amplifier 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": prod23132701,
    "adItemId": 600004,
    "bid": 0.6,
    "status": "enabled",
    "itemImageUrl": https://scene7.samsclub.com/is/image/samsclub/0004200094484_A?$DT_PDP_BB$"
    "itemPageUrl": "https://www.samsclub.com/p/quilted-northern-ultra-soft-strong-toilet-paper-32-rolls-271-sheets/prod23132701",
    "name": "TV Console",
    "reviewStatus": "pending ",
    "reviewReason ": "text123"
  }
]

HTTP Status Code

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

Add Ad Item to an Ad Group

Description: Used to add new ad item to the ad group in a campaign.

End Point: /api/v1/adItems

HTTP Method: POST

Body Parameters

Parameter Description 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 clicks 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 in dollars
Minimum bid amount is:
  1. $0.20 for auto-bid campaigns
  2. $0.30 for keyword-bid campaigns
  3. $1 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.
status Status of ad item String Y

Expected Values: enabled, disabled, deleted

Note: You cannot delete an item from a campaign that has gone live

Sample Request

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
curl --location 
'https://developer.api.us.stg.walmart.com/api-proxy/service/sp/api-sams/v1/api/v1/adItems'  
--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,
    "itemId": "prod11640583",
    "bid": 1.25,
    "status": "enabled"
}'

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
OkHttpClient client = new OkHttpClient().newBuilder().build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, 
"[
    {
        "campaignId": 1234, 
        "adGroupId": 1234, 
        "itemId": "prod11640583", 
        "bid": "1.25", 
        "status": "enabled" 
    }
]");
Request request = new Request.Builder()
.url("https://developer.api.us.stg.walmart.com/api-proxy/service/sp/api-sams/v1/api/v1/adItems") 
.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
33
34
const axios = require('axios'); 
let data = JSON.stringify([ 
{ 
    "campaignId": 1234,
    "adGroupId": 1234,
    "itemId": "prod11640583",
    "bid": 1.25,
    "status": "enabled"
} 
]); 
let config = { 
method: 'post', 
maxBodyLength: Infinity, 

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

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
22
23
24
25
import requests 
import json 

url = "https://developer.api.us.stg.walmart.com/api-proxy/service/sp/api-sams/v1/api/v1/adItems"  
payload = json.dumps([ 
{ 
    "campaignId": 1234 
    "adGroupId": 1234, 
    "itemId": "prod11640583", 
    "bid": "1.25", 
    "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("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 response is failure String
adItemId ID of the ad item Integer

Sample Response

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

HTTP Status Code

Status Code Description Possible Error Messages
200 OK
  • Ad Group Id validation failed
  • Could not retrieve channel for Ad Group
  • The campaignId= <campaignId> provided for one of the items is not associated to adGroupId= <adGroupId>
  • Record id does not match with adgroup/item
  • You are not authorized to edit this adgroup
  • Bid should be higher than <floorCpc>
  • Item Id not found
400 Bad Request
  • Maximum allowed size in batch is 50
  • Multiple request for same item id within ad group is not allowed
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 Ad Item

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

End Point: api/v1/adItems

HTTP Method: PUT

Body Parameters

Parameter Description 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 in dollars
Minimum bid amount is:
  1. $0.20 for auto-bid campaigns
  2. $0.30 for keyword-bid campaigns
  3. $1 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.
status Status of ad item String Y

Expected values: enabled, disabled, deleted

Note: You cannot delete an item from a campaign that has gone live

Sample Request

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
curl --location --request PUT 
'https://developer.api.us.stg.walmart.com/api-proxy/service/sp/api-sams/v1/api/v1/adItems' 
--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, 
     "itemId": "prod11640583", 
     "bid": 2.0,
    "status": "enabled"
}'

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
OkHttpClient client = new OkHttpClient().newBuilder().build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, 
"[
    {
        "campaignId": 1234,
        "adGroupId": 1234,
        "itemId": "prod11640583",
        "bid": 2.0,
        "status": "enabled"
    }
]");
Request request = new Request.Builder()
.url("https://developer.api.us.stg.walmart.com/api-proxy/service/sp/api-sams/v1/api/v1/adItems")
.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
33
34
const axios = require('axios'); 
let data = JSON.stringify([ 
{ 
    "campaignId": 1234, 
    "adGroupId": 1234, 
    "itemId": "prod11640583", 
    "bid": 2.0, 
    "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/adItems', 

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
22
23
24
import requests 
import json 

url = "https://developer.api.us.stg.walmart.com/api-proxy/service/sp/api-sams/v1/api/v1/adItems" 
payload = json.dumps([ 
{ 
    "campaignId": 1234, 
    "adGroupId": 1234, 
    "itemId": "prod11640583", 
    "bid": 2.0, 
    "status": "enabled" 
} 
]) 
headers = { 
'Authorization': 'Bearer ***************',
'wm_consumer.id': '************', 
'wm_sec.key_version': '2', 
'wm_sec.auth_signature': '************', 
'wm_qos.correlation_id': '12345', 
'wm_consumer.intimestamp': '1707205605000',
'Content-Type': 'application/json'
} 
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 response 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"
  }
]

HTTP Status Code

Status Code Description Possible Error Messages
200 OK
  • Ad Group Id validation failed
  • Could not retrieve channel for Ad Group
  • The campaignId= <campaignId> provided for one of the items is not associated to adGroupId= <adGroupId>
  • Record id does not match with adgroup/item
  • You are not authorized to edit this adgroup
  • Bid should be higher than <floorCpc>
  • Item Id not found
400 Bad Request
  • Maximum allowed size in batch is 50
  • Multiple request for same item id within ad group is not allowed
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