Add Itemsets to Campaigns
This API allows users to associate featured and halo (both auto created and custom) measurement itemsets with a campaign or remove their campaign association
Note: Halo itemsets association and removal is allowed only for campaigns with start date on or after 04/01/2025. For older campaigns the default behavior will continue
URL: POST /api/v1/itemsetAssociation
Request Parameters
| Parameter | Notes | Type | Required | Possible Values |
|---|---|---|---|---|
| advertiserId | ID of the advertiser | integer | Y | Unique numeric identifier |
| campaignId | ID of the campaign | integer | Y | Unique numeric identifier |
| itemsetId | ID of the featured itemset Note: itemset needs to be BUILT before it can be associated to campaigns | integer | Y | If omitted, the featured itemset will be removed from the campaign. • If the campaign had auto-created halo itemsets (BRAND or CATEGORY), they will also be removed. |
| itemsetType | Type of itemset being associated. Should always be | string | N | Value: featured |
| haloAssociationType | Type of Halo association Note:
| string | N |
|
| haloItemsetId | ID of the custom halo itemset to be associated. Note: If haloAssociationType is BRAND or CATEGORY, parameter haloItemsetId will not be considered | integer | Condiotional Note: Required if haloAssociationType is CUSTOM | Valid ID value |
To remove an itemset:
- To remove featured itemset: Omit itemsetId from the request. Note that removing an itemset will also remove any auto-created halo itemsets (BRAND or CATEGORY) associated to the campaign. CUSTOM halo itemset will not be removed
- To remove Halo itemset: Set haloAssociationType = NONE
Support for Adding or Removing Measurement Itemset by Campaign Status
| Draft | Scheduled | Live | Paused | Complete | Notes | |
|---|---|---|---|---|---|---|
| Add/Remove Measurement Itemset | ✅ | ✅ | ✅ | ✅ | ⚠️ | ⚠️ : Extend endDate to edit if campaign is Complete |
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 |
| Content-Type | Format of the message body | Y | application/json |
| WM_CONSUMER.ID | Unique ID for consumer. 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 more information |
| WM_SEC.AUTH_SIGNATURE | Signature for authentication | Y | Use the signature generator code from Getting Started Guide to generate this value |
| WM_SEC.KEY_VERSION | 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.intimestamp | Timestamp for which the auth signature is generated. Use Unix epoch format for the timestamp. | Y | Use the signature generator code from Getting Started Guide to generate this value |
Sample Request - Associate featured itemset and an auto created BRAND halo itemset
curl --request POST 'https://developer.api.us.stg.walmart.com/api-proxy/service/display/api/v1/api/v1/itemsetAssociation' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer <auth_token>' --header 'WM_SEC.AUTH_SIGNATURE: **************' \ --header 'WM_SEC.KEY_VERSION: 1' \ --header 'WM_CONSUMER.ID: *************' \ --header 'WM_CONSUMER.intimestamp: 1565309779' --data '[ { "advertiserId": 1, "campaignId": 1, "itemsetId": 1234, "itemsetType": "FEATURED", "haloAssociationType": "BRAND" }
]' Sample Request - Associate custom halo itemset
curl --request POST 'https://developer.api.us.stg.walmart.com/api-proxy/service/display/api/v1/api/v1/itemsetAssociation' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer <auth_token>' --header 'WM_SEC.AUTH_SIGNATURE: **************' \ --header 'WM_SEC.KEY_VERSION: 1' \ --header 'WM_CONSUMER.ID: *************' \ --header 'WM_CONSUMER.intimestamp: 1565309779' --data '[ { "advertiserId": 1, "campaignId": 73512, "itemsetId": 1234, "itemsetType": "FEATURED", "haloAssociationType": "CUSTOM", "haloItemsetId": 123 }
]' Sample Request - Associate no halo itemset
curl --request POST 'https://developer.api.us.stg.walmart.com/api-proxy/service/display/api/v1/api/v1/itemsetAssociation' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer <auth_token>' --header 'WM_SEC.AUTH_SIGNATURE: **************' \ --header 'WM_SEC.KEY_VERSION: 1' \ --header 'WM_CONSUMER.ID: *************' \ --header 'WM_CONSUMER.intimestamp: 1565309779' --data '[ { "advertiserId": 1, "campaignId": 73512, "itemsetId": 1234, "itemsetType": "FEATURED" }
]' Sample Request - Batch operation
curl --request POST 'https://developer.api.us.stg.walmart.com/api-proxy/service/display/api/v1/api/v1/itemsetAssociation' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer <auth_token>' --header 'WM_SEC.AUTH_SIGNATURE: **************' \ --header 'WM_SEC.KEY_VERSION: 1' \ --header 'WM_CONSUMER.ID: *************' \ --header 'WM_CONSUMER.intimestamp: 1565309779' --data '[ { "advertiserId": 1, "campaignId": 1, "itemsetId": 1234, "itemsetType": "FEATURED", "haloAssociationType": "BRAND" }, { "advertiserId": 1, "campaignId": 73512, "itemsetType": "FEATURED", "haloAssociationType": "CUSTOM", "haloItemsetId": 123 }
]' Sample Request - Remove Featured and Auto Halo Associations
curl --request POST 'https://developer.api.us.stg.walmart.com/api-proxy/service/display/api/v1/api/v1/itemsetAssociation' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer <auth_token>' --header 'WM_SEC.AUTH_SIGNATURE: **************' \ --header 'WM_SEC.KEY_VERSION: 1' \ --header 'WM_CONSUMER.ID: *************' \ --header 'WM_CONSUMER.intimestamp: 1565309779' --data '[ { "advertiserId": 1, "campaignId": 73512, "itemsetType": "FEATURED" }
]' Sample Request - Invalid featured itemset id
curl --request POST 'https://developer.api.us.stg.walmart.com/api-proxy/service/display/api/v1/api/v1/itemsetAssociation' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer <auth_token>' --header 'WM_SEC.AUTH_SIGNATURE: **************' \ --header 'WM_SEC.KEY_VERSION: 1' \ --header 'WM_CONSUMER.ID: *************' \ --header 'WM_CONSUMER.intimestamp: 1565309779' --data '[ { "advertiserId": 1, "campaignId": 73512, "itemsetType": "FEATURED", "haloAssociationType" : "CUSTOM", "itemsetId": 1234, "haloItemsetId": 123 }
]' Sample Request - Invalid haloItemsetId
curl --request POST 'https://developer.api.us.stg.walmart.com/api-proxy/service/display/api/v1/api/v1/itemsetAssociation' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer <auth_token>' --header 'WM_SEC.AUTH_SIGNATURE: **************' \ --header 'WM_SEC.KEY_VERSION: 1' \ --header 'WM_CONSUMER.ID: *************' \ --header 'WM_CONSUMER.intimestamp: 1565309779' --data '[ { "advertiserId": 1, "campaignId": 73512, "itemsetType": "FEATURED", "haloAssociationType" : "CUSTOM", "itemsetId": 1234, "haloItemsetId": 123 }
]' Response
| Element | Description | Required | Type | Possible Values |
|---|---|---|---|---|
| code | The response code can have following values:
Click here for more information about Status Codes and Errors | Y | string | success, failure |
| details | Details will populate success or error message depending upon value of code | Y | array<string> | Refer to this link for detailed error messages |
| campaignId | ID of the campaign. Only return with code=success | Y | integer | |
| itemsetId | ID of the item set Only return with code=success | Y | integer | |
| message | High-level summary of the error, when available. | N | string | |
| errors | Detailed information about one or more errors, including the affected field (when applicable), error code, and a human-readable description. | N | array<object> |
errors array object details
| Field | Description | Optional field/Nullable? | Type | Possible values |
|---|---|---|---|---|
| field | JSON field associated with the error. Omitted if the error applies to the request as a whole. | N | string | |
| errorType | Machine-readable error code that uniquely identifies the error condition. Applications should use this value for error handling logic. | Y | string | |
| description | Human-readable explanation of the error, including why the request failed and, when possible, how to resolve it | Y | string |
Sample Response - Associate featured itemset and an auto created BRAND halo itemset (Success)
[ { "code": "success", "details": [ "ITEMSET_CAMPAIGN_ASSOCIATION_SUCCESS" ], "campaignId": 1, "itemsetId": 1234 }
]Sample Response - Associate custom halo itemset (Success)
[ { "code": "success", "details": [ "ITEMSET_CAMPAIGN_ASSOCIATION_SUCCESS" ], "campaignId": 1, "itemsetId": 1234 }
]Sample Response - Associate no halo itemset (Success)
[ { "code": "success", "details": [ "ITEMSET_CAMPAIGN_ASSOCIATION_SUCCESS" ], "campaignId": 1, "itemsetId": 1234 }
]Sample Response - Batch operation (Success)
[ { "code": "success", "details": ["ITEMSET_CAMPAIGN_ASSOCIATION_SUCCESS"], "campaignId": 1, "itemsetId": 1234 }, { "code": "success", "details": ["ITEMSET_CAMPAIGN_ASSOCIATION_SUCCESS"], "campaignId": 1, "itemsetId": 1234 } ]Sample Response - Remove Featured and Auto Halo Associations (Success)
[ { "code": "success", "campaignId": 73512, "details": [ "REMOVE_ITEMSET_CAMPAIGN_ASSOCIATION_SUCCESS" ] }
]Sample Response - Invalid featured itemset id(Success) - NA
Sample Response - Invalid featured itemset id
[ { "code": "failure", "details": [ "string" ], "message": "string", "errors": [ { "field": "string", "errorType": "string", "description": "string" } ] }
]Sample Response - Invalid haloItemsetId(Success) - NA
Sample Response - Invalid haloItemsetId
[ { "code": "failure", "details": [ "string" ], "message": "string", "errors": [ { "field": "string", "errorType": "string", "description": "string" } ] }
]Updated 3 days ago
Did this page help you?
